From 04e5da1a6bc74220acc82c06405558ed765f0233 Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Tue, 7 Apr 2020 12:46:05 -0500 Subject: [PATCH] HPT resizing option - KVM only Signed-off-by: Jeff Scheel --- DeviceTree/ch_devtree_system.xml | 3650 ++++++++++++------------ Platform/ch_system_reqs.xml | 1473 +++++----- Virtualization/ch_lpar_option.xml | 4354 ++++++++++++++++------------- 3 files changed, 4902 insertions(+), 4575 deletions(-) diff --git a/DeviceTree/ch_devtree_system.xml b/DeviceTree/ch_devtree_system.xml index b672394..eaa1e08 100644 --- a/DeviceTree/ch_devtree_system.xml +++ b/DeviceTree/ch_devtree_system.xml @@ -1,7 +1,7 @@ System Binding - +
LoPAR Boot Flow - + This section gives a system boot process overview and defines the enhancements to the standard OF boot process that are present in the boot process for an LoPAR platform. - +
Boot Overview - The platform performs a normal OF boot (see + The platform performs a normal OF boot (see , as stated in the Core Practice Document, Section 4.2.3, Start-up script evaluation. LoPAR platforms provide an additional capability to assist the user in choosing which of several OSs to boot. A key sequence can be used to interrupt the - normal boot flow and present the user with a + normal boot flow and present the user with a multiboot menu, which can be either graphical or text-based at the discretion of the platform’s firmware, from which the user can choose one of the installed or installable OSs. Presenting the user with this choice can also be made the default mode of operation - at platform boot time, by means of the - auto-boot? and + at platform boot time, by means of the + auto-boot? and menu? configuration variables. - An overview of a platform boot sequence and the additions of the + An overview of a platform boot sequence and the additions of the multiboot menu are given below: @@ -59,166 +59,166 @@ - + The boot flow described above occurs after all of the devices have - been probed (i.e., by the execution of - probe-all); see - additional requirements for + been probed (i.e., by the execution of + probe-all); see + additional requirements for probe-all method. The boot sequence defaults to a normal boot if the boolean variable - - auto-boot? is true and + + auto-boot? is true and diagnostic-mode? is false. In this situation, the system shall then boot from information contained in the configuration - variables - boot-device and + variables + boot-device and boot-file. - From the boot sequence above, entry to the - multiboot menu may occur anywhere after step ‘f’, - banner, if the platform key + From the boot sequence above, entry to the + multiboot menu may occur anywhere after step ‘f’, + banner, if the platform key sequence (multiboot menu) has been depressed or in step - ‘i’ if the boolean variable + ‘i’ if the boolean variable menu? is true. - +
Additional Requirements for probe-all Method - - Before probing for plug-in devices, OF shall execute the - probe method, as with + + Before probing for plug-in devices, OF shall execute the + probe method, as with execute-device-method, of any built-in device nodes. - The order of evaluation shall ensure that the + The order of evaluation shall ensure that the probe method of a parent device node is executed - before the + before the probe method of any of its children. Note: During this built-in probing, /rom nodes will - locate ROM based OSs. The FCode for these devices can publish their + locate ROM based OSs. The FCode for these devices can publish their “bootinfo” properties that are used during the multiboot scenario as described below. - +
- +
LoPAR Multiboot - - The boot choices identified to the user are defined by + + The boot choices identified to the user are defined by bootinfo objects hich are located on various system - media. Each + media. Each bootinfo object contains information about one OS, such as its name and description, an icon depicting it, and an OF command - sequence to load and execute it. The locations where - bootinfo objects can be found are specified by OF + sequence to load and execute it. The locations where + bootinfo objects can be found are specified by OF device-specifiers that are the values of - configuration variables, the names of which are of the form - “bootinfo-nnnnn”, where - “nnnnn” is OS-specific. These + configuration variables, the names of which are of the form + “bootinfo-nnnnn”, where + “nnnnn” is OS-specific. These configuration variables are stored in the System - Partition in NVRAM and are published in the - device tree as properties under the - /options node. The - multiboot menu will use these - configuration variables to locate and parse + Partition in NVRAM and are published in the + device tree as properties under the + /options node. The + multiboot menu will use these + configuration variables to locate and parse bootinfo to obtain the OS icon, description, etc. - In addition to the - bootinfo-nnnnn configuration variables, the + In addition to the + bootinfo-nnnnn configuration variables, the multiboot menu will search the device tree for nodes - containing + containing “bootinfo” properties, which specify that - the node can supply a + the node can supply a bootinfo object. This is particularly useful for OSs contained in ROMs. Note: The order prescribed by probe-all guarantees - that these properties be created before the + that these properties be created before the multiboot menu has been invoked. - Different versions of the same OS may each have their own - bootinfo and associated + Different versions of the same OS may each have their own + bootinfo and associated configuration variables. Although it is possible to - put + put bootinfo in any media location that OF can read, this specification defines standard locations for various types of media, to - allow the firmware to establish the + allow the firmware to establish the bootinfo configuration variables automatically in many cases. - +
- +
Bootinfo Configuration Variables - - A - bootinfo configuration variable is any + + A + bootinfo configuration variable is any configuration variable that meets the following requirements: - - + + - Its name is of the form - “bootinfo-nnnnn”, where + Its name is of the form + “bootinfo-nnnnn”, where nnnnn is a string of at most 22 characters from the set of valid characters for OF configuration variable names. The exact - value of + value of “nnnnn” for a particular OS may be chosen by that OS. The naming convention for the OS should be chosen to avoid possible naming conflicts between OS vendors. - + - Its value is an OF + Its value is an OF device-specifier that identifies an object (e.g. disk - file, tape file, disk partition or - /rom child node) whose contents are a + file, tape file, disk partition or + /rom child node) whose contents are a “bootinfo object” as defined below. - - + +
- +
Bootinfo Properties - - Any node in the device tree can have a + + Any node in the device tree can have a “bootinfo” property whose value specifies - the arguments to use in opening that device in order to access its + the arguments to use in opening that device in order to access its bootinfo object. “bootinfo” S - property name locates the node’s + property name locates the node’s bootinfo object - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string The presence of this property signifies that the device has an - associated + associated bootinfo object. The value is a text string such - that when this device’s node + that when this device’s node open method is called, the value of text string that - is passed to the device’s node - open method is + is passed to the device’s node + open method is “my-args”. When so opened, subsequent - calls to the node’s + calls to the node’s “read” method will yield the contents of - the node’s + the node’s bootinfo object. - +
- +
Standard Locations for Bootinfo Objects - - The standard locations for + + The standard locations for bootinfo objects on various LoPAR media and - partition types is shown in the table below. An OS must put its + partition types is shown in the table below. An OS must put its bootinfo object in the standard location in order to - guarantee interoperability with the LoPAR + guarantee interoperability with the LoPAR multiboot menu mechanism. - + - Standard Pathnames for - <emphasis>bootinfo.txt</emphasis> File + <title>Standard Pathnames for + <emphasis>bootinfo.txt</emphasis> File @@ -285,8 +285,8 @@ device:bootinfo - bootinfo is the value of the - “bootinfo” property in a + bootinfo is the value of the + “bootinfo” property in a /rom child node @@ -314,31 +314,31 @@ (disk): ALIAS EXAMPLE: bootinfo-aix-4.3=disk:2 (The contents of partition 2, which is - probably a “0x41” partition, on the default disk, is the + probably a “0x41” partition, on the default disk, is the bootinfo.txt file for a version of the AIX OS.) bootinfo-nt-4.0=disk:\os\winnt\bootinfo.txt NON-ALIAS EXAMPLE: bootinfo-aix-4.4=/pci@ff500000/pci3,1000@10/sd0,0:3 (The contents of partition 3, which is probably a “0x41” partition, on the - SCSI disk at target 0 unit 0, is the + SCSI disk at target 0 unit 0, is the bootinfo.txt file for a version of the AIX OS.) - + - +
Bootinfo Objects - - The information used by OF to display information in the + + The information used by OF to display information in the multiboot menu and to locate and process an OS load image is contained - within a sequence of text that is called a + within a sequence of text that is called a bootinfo object. The text comprising the bootinfo - object uses SGML syntax, as defined in + object uses SGML syntax, as defined in , with tags identifying the subordinate elements. - The following outline is a summary of the organization of the + The following outline is a summary of the organization of the bootinfo object. Elements at the same level do not have any required order. The tags are illustrated in upper case, but shall be processed in a case-insensitive manner. @@ -361,23 +361,23 @@ ]]> - + Notes: - - + + If ‘SIZE’ is not present, assume default of 64,64. If ‘COLOR-SPACE’ is not present, assume default of 3,3,2. - + Another <chrp-boot> tag sequence could define a different boot selection - + LoPAR platforms will recognize only the tags between the beginning <chrp-boot> tag until the end </chrp-boot> tag. If @@ -386,25 +386,25 @@ additional selections would also be presented to the user as boot options. - - + +
Bootinfo Entities - + SGML provides “entities” that provide symbolic names for text. When the entity names are contained within & and ‘;’, the entity is replaced with text as defined by the entity; i.e., entities provide a “macro” substitution - capability. The + capability. The bootinfo object may use entities to supply pathname components that depend upon the location of the file. Also, entities have been defined for the standard SMGL Tags for the presence of the ‘<‘, ‘&’ and ‘>’ characters in the text as &lt;, &amp; and &gt;. Within the <BOOT-SCRIPT> element, the following entities are defined with - respect to the fully qualified pathname of the + respect to the fully qualified pathname of the bootinfo object: - + device @@ -412,28 +412,28 @@ the device component. - + partition the partition component. - + directory the directory component. - + filename the filename component. - + full-path @@ -441,7 +441,7 @@ - + The fully qualified pathname could be represented by the following text: @@ -449,43 +449,43 @@ Note: Underlined portions illustrate where entities are positioned within the full pathname.
- +
Bootinfo Character Sets The character set used by the bootinfo.txt file is ISO-8859-1 (Latin-1). Element tags and entity names are not case sensitive; all other text is case sensitive.
- +
Element Tag Descriptions The following sections describe each of the element tags and how they are used.
- +
CHRP-BOOT Element This element provides the grouping for each OS that is represented within a single bootinfo.txt file. Multiple CHRP-BOOT sections are allowed within a single bootinfo.txt file.
- +
OS-NAME element This element contains the complete name of the OS.
- +
BOOT-SCRIPT element This element contains an OF script that is executed when the OS defined by this CHRP-BOOT section is selected to be loaded. Each line of this element is processed as if it were entered from the input device of the user interface. Typically, the last line of this script would contain - a + a boot command; the pathname of the OS’s load image can be constructed with the entities described above.
- +
ICON element This element describes the OS icon that can be displayed by the @@ -522,17 +522,17 @@ - + Note 2: Hex string would be 8192 characters for a size=64,64 in the above example. For the two examples below, the tags have been indented and separated by line feeds for each start/end tag pair to make a more readable script style. - + AIX Bootinfo Object Example: - + AIX 4.2.D.0 AIX 4.2.D.0 @@ -556,83 +556,83 @@
- +
Multiboot Menu If the boot sequence is interrupted by the multiboot key sequence, - then the firmware shall present a + then the firmware shall present a multiboot menu that provides at least the functions listed below. The form of the menu (e.g. graphical or text- oriented) and the selection mechanism (e.g. numbered choices, arrow keys, or mouse) are platform-dependent. Multiboot Required Functions: - - + + Locate all bootinfo objects specified by bootinfo configuration - variables and device node - “bootinfo” properties. For each + variables and device node + “bootinfo” properties. For each bootinfo object, present a choice corresponding to each valid <chrp-boot> section contained therein. For each such choice, allow the user to either: - - + + - Execute the contents of that + Execute the contents of that bootinfo object’s <boot-script> element. - + - Set the + Set the boot-command configuration variable to the contents - of that + of that bootinfo object’s <boot-script> element. - + - + Present a choice corresponding to each install device, which, when invoked, will attempt to locate a bootinfo object at the device’s standard location (see Table 1). - + Allow the user to manage configuration variables - + Allow the user to invoke the OF user interface - - + + Additional options that could be implemented would be to provide a means to get to diagnostics or specific platform options. There shall be at least one key sequence to enter the multi-boot platform function for an LoPAR platform. Note: OS have the responsibility to update the NVRAM - System Partition Variable to reflect a change where the + System Partition Variable to reflect a change where the bootinfo.txt file is located; e.g., moving to a different disk device. Also, the OS is responsible for maintaining the - contents of the + contents of the bootinfo.txt file. - +
- + - +
Reboot-Command Variable Description - + The OS can cause OF to execute a specified sequence of commands at - the next boot by setting the value of the + the next boot by setting the value of the reboot-command configuration variable. LoPAR firmware implementations shall implement the following configuration variable. - + reboot-command(-- addr len) [N] @@ -642,37 +642,37 @@ zero or more lines of text, with lines separated by either <return>, <linefeed>, or <return><linefeed>. - During firmware start-up, just prior to checking the + During firmware start-up, just prior to checking the auto-boot? configuration variable for automatic - booting, the firmware shall check the value of + booting, the firmware shall check the value of reboot-command. If the value is not the empty - string, the firmware shall save the value to a temporary location, set + string, the firmware shall save the value to a temporary location, set reboot-command to the empty string, and evaluate the saved value as though it were a series of user interface command lines. - If the evaluation of + If the evaluation of reboot-command returns without executing, the firmware shall proceed with its normal start-up sequence. In typical - usage, however, the value of - reboot-command will include a + usage, however, the value of + reboot-command will include a boot command that starts a client program and does not return. - +
- + - +
LoPAR Processor - + OF defines a minimum cell size of 32 bits; therefore, only one cell is necessary to represent addresses up to 4GB (32 bits). Two cells are necessary to represent addresses above 4GB and within 64 bits. Also, two cells are necessary to represent sizes greater than 4GB. - +
Processor Endian-ness Support LoPAR requires the use of PA processors that support Big-Endian @@ -680,10 +680,10 @@ Little-Endian storage format in addition to Big-Endian storage format.
- +
Multi-Threading Support - + The processors used in some platforms support multiple threads of execution. This processor model differs from Symmetric Multi-Processors in that the multiple threads of execution share the processor hardware to @@ -692,23 +692,23 @@ processor is represented with a single processor node having multiple interrupt server numbers. The OS is then free to start and stop multi-threading as the processing environment dictates. The client - interface call + interface call start-cpu, operates on the full CPU as presented in the device tree, upon successful completion, the started CPU is running in single threaded mode, the active thread being the one associated with - the first interrupt server number in the + the first interrupt server number in the “ibm,ppc-interrupt-server#s” property. - The client interface calls: + The client interface calls: stop-self, idle-self, resume-cpu are all defined to operate on the full CPU when called in single threaded mode, the behavior of these calls if called with multiple threads active is implementation dependent, it is suggested that the implementation deactivate all but one thread before performing the call’s standard function. - +
- +
- +
OF Platform Extensions This section defines OF properties, methods, device tree structure @@ -716,107 +716,107 @@ 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 + must have the string “ibm,” as a prefix to the property name. - + - Property names prefixed with the string + 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 + 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 + 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”. + + 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, + 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. + The drc-type encoded with + encode-string. Examples include “MEM” “PHB” and “CPU” - The drc-name-prefix encoded with - encode-string. + 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 + 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 + 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 + 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 + 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 + The drc-power-domain encoded with encode-int. - - The following properties have been replaced by the + + The following properties have been replaced by the “ibm,drc-info” but are documented here for legacy purposes: @@ -831,12 +831,12 @@ prop-encoded-array: An integer encoded as with encode-int, followed by a list of integers also - encoded as with + 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 + 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 @@ -850,7 +850,7 @@ property name denotes an integer index (value of the - entry in the + entry in the “ibm,drc-indexes” property) for the connector between the node and the node’s parent. @@ -869,7 +869,7 @@ prop-encoded-array: An integer encoded as with encode-int, followed by a list of strings each - encoded as with + 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 @@ -886,19 +886,19 @@ property name gives the power domain number for each connector associated with the node, which is the domain number to be used - in the + 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 + 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 + 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 + 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 @@ -917,16 +917,16 @@ prop-encoded-array: An integer encoded as with encode-int, followed by a list of strings each - encoded as with + 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 + defined connector types specified in . - +
Currently Defined DR Connector Types @@ -1272,14 +1272,14 @@ property name, defines the phandle for the node. - prop-encode-array: An integer encoded with + prop-encode-array: An integer encoded with encode-int. - + - +
OF Root Node This section defines additional properties and methods associated @@ -1294,7 +1294,7 @@ Notes: - + This requirement ensures that the PHB would have a stable unit address. Violations of this rule may require reinstallation of an @@ -1310,53 +1310,53 @@ 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 + 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 + 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 + 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 + 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 + Standard + property name, encoded as with encode-int, that represents the primary system bus speed (in hertz). - + “ibm,extended-clock-frequency” @@ -1366,20 +1366,20 @@ of multi-giga-hertz quantities. prop-encoded-array: Consisting of two cells - (freq-hi, freq-lo) each encoded as with + (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 + Standard + property name, encoded as with encode-string, that contains the identification of - the computer system (Reference the - “name” property in + 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 @@ -1394,36 +1394,36 @@ system-id. - + “model” [S] - Standard + 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 + 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 + Standard property name that is a printable string identifying the platform as LoPAR Compliant. - prop-encoded-array: Text string, encoded as with + prop-encoded-array: Text string, encoded as with encode-string. - The value of this property is a string, + The value of this property is a string, “chrp” which identifies the platform is LoPAR Compliant. - + “ibm,lpar-capable” @@ -1435,7 +1435,7 @@ prop-encoded-array: <NULL> - + “ibm,converged-loc-codes” @@ -1448,7 +1448,7 @@ prop-encoded-array: <NULL> - + “ibm,max-boot-devices” @@ -1458,11 +1458,11 @@ 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 + prop-encoded-array: an integer encoded as with encode-int. - + “ibm,aix-diagnostics” @@ -1473,7 +1473,7 @@ prop-encoded-array: <NULL> - + “ibm,diagnostic-lic” @@ -1484,11 +1484,11 @@ diagnostic services. prop-encoded-array: one or more encapsulated package - handles encoded as with + handles encoded as with encode-int. - + “ibm,io-server-lic” @@ -1498,11 +1498,11 @@ services. prop-encoded-array: one or more encapsulated package - handles encoded as with + handles encoded as with encode-int. - + “ibm,plat-res-int-priorities” @@ -1512,16 +1512,16 @@ own use. prop-encoded-value: one or more ( - interrupt priority, range) pairs, where + 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 + 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” @@ -1529,21 +1529,21 @@ property name indicates the platform’s default setting for the EEH option. - prop-encoded-array: An integer encoded as with + 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 + prop-encoded-array: string encoded as defined in . - +
Example Encoding Strings @@ -1627,7 +1627,7 @@
- + “ibm,partition-no” [S] @@ -1635,11 +1635,11 @@ logical partition as established by the Hardware Management Console. prop-encoded-array: The logical partition number is a one cell - integer encoded as with + integer encoded as with encode-int. - + “ibm,partition-name” [S] @@ -1649,7 +1649,7 @@ prop-encoded-array: A NULL terminated string. - + “ibm,platform-hardware-notification” @@ -1660,9 +1660,9 @@ special handling by the OS, such as in response to a hardware errata. - prop-encoded-array: An integer encoded as with + prop-encoded-array: An integer encoded as with encode-int followed by a list of strings encoded as - with + 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 @@ -1672,17 +1672,17 @@ 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 + 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” @@ -1700,7 +1700,7 @@ Error Log indicators for errors it detects. - + “ibm,fru-9006-deactivate” @@ -1719,17 +1719,17 @@ indicators is platform and service procedure dependent. - + “compatible” [S] - Standard + Standard property name that conveys the platform architecture identifiers. - prop-encoded-array: The concatenation, with + prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, - each encoded with + 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 @@ -1740,24 +1740,24 @@ “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 + 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 + description of the “compatible” property, implementations should place the “LoPAR-<LoPPR version>-<Manufacturer>-<Manufacturer Version>” - substring after values that were present in the + 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” @@ -1765,14 +1765,14 @@ property name to define the maximum vios function level that a client shall permit. - prop-encoded-array: An integer encoded as with + prop-encoded-array: An integer encoded as with encode-int that represents the maximum VIOS level - that the client shall negotiate. See + that the client shall negotiate. See for the definition of the values of this property. - + “ibm,partition-performance-parameters-level” @@ -1782,9 +1782,9 @@ prop-encoded-array: An integer encoded as with encode-int that represents the level of partition performance parameter - reporting supported by the platform (See + reporting supported by the platform (See ). - + Level of Partition Performance Parameter Reporting Supported @@ -1832,7 +1832,7 @@
- + “ibm,preconfigure-usb-kvm” @@ -1857,12 +1857,12 @@ actually switched to the appropriate KVM switch port. - + “ibm,enable-ci64-capable” - property name to define the platform supports the + property name to define the platform supports the “ibm,enable-ci64” method in the Client Interface. @@ -1870,7 +1870,7 @@ property. - + “ibm,migratable-partition” @@ -1881,7 +1881,7 @@ prop-encoded-array: <NULL> - + “ibm,extended-address” [S] @@ -1894,21 +1894,21 @@ 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 + remove operation. See also Note 2 in . prop-encoded-array: None, this is a name only property. - + “ibm,managed-address-types” @@ -1916,14 +1916,14 @@ property name that conveys the platform's supported types of external addresses that are reprogrammable. - prop-encoded-array: The concatenation, with + prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings as - described in - , each encoded with + described in + , each encoded with encode-string. - + - Address types supported in + <title>Address types supported in <emphasis role="bold"><literal>“ibm,managed-address-types”</literal></emphasis> property @@ -1984,7 +1984,7 @@
- + “ibm,service-indicator-mode” @@ -1992,20 +1992,20 @@ property name indicates in which service indicator mode the platform is operating. - prop-encoded-array: an integer encoded as with + 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. - + @@ -2013,7 +2013,7 @@ “ibm,guid-partition-table” - property name indicates that the partition supports disks + property name indicates that the partition supports disks with the GUID Partition Table. prop-encoded-array: <NULL> @@ -2024,7 +2024,7 @@ “ibm,linux-le-capable” - property name indicates that the partition is capable of + property name indicates that the partition is capable of supporting boot of Little Endian Linux. prop-encoded-array: <NULL> @@ -2037,14 +2037,14 @@ property name specifies a universally unique identifier for this partition. - prop-encoded-array: A string of data as described below, encoded as with + 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 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 + The random bits are generated in an implementation-dependent manner to achieve a projected probability of collision of not greater than one in 260. @@ -2171,23 +2171,23 @@
- - For the GET_PARTNER_UUID subfunction (See ), the data is + + 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 + 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 + 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 @@ -2197,19 +2197,19 @@ 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” @@ -2223,12 +2223,12 @@ Descendents of a node containing this property will be in the same reset domain. - prop-encoded-array: An integer encoded as with + 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” @@ -2236,128 +2236,128 @@ 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 + 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 + “/” (the root node). Boot Loader Note: The suggested behavior for boot loader client programs: - + - Check the “ibm,rpa-client-config” + 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,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 + 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 + 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 + 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 + 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 + within the ibm,architecture.vec structure option vectors represent policies. When set, and an associated condition is detected, - the + 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 + 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 + the , while not attempting access - to potentially optional SPRs or the MSR prior to invoking the + 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 + Most of the IBM,RPA-Client-Config ELF header functionality is - subsumed by the + subsumed by the ibm,client-architecture-support root method. However, - the + the ibm,client-architecture-support root method does not - support the functionality specified through the ns.min-load field of the + 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 + When booting a client program, firmware processes an IBM,RPA-Client-Config ELF header if present; a - subsequent call of the + subsequent call of the ibm,client-architecture-support root method with - conflicting values in the + 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: + ibm,architecture.vec = a + PVR-list: + Number-of-option-vectors: option-vectors[Number-of-option-vectors + 1] PVR-list = - Terminator-list-entry | + Terminator-list-entry | Non-terminator-list: Terminator-list-entry Non-terminator-list = Non-terminal-list-entry | @@ -2368,12 +2368,12 @@ 4-byte-mask: 4-byte-PVR-value - Terminator-list-entry = - List-entry such that ! - 4-byte-mask & + Terminator-list-entry = + List-entry such that ! + 4-byte-mask & 4-byte-PVR-value != 0x00000000 - Non-terminator-list-entry = List-entry such that ! + Non-terminator-list-entry = List-entry such that ! 4-byte-mask & 4-byte-PVR-value == 0x00000000 @@ -2385,70 +2385,70 @@ 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 + -- 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 + of option vectors in the vector expansion (see definition of Number-of-option-vectors above). This is followed by - 1-255 + 1-255 option-vectors (see definition above) and potentially - a 256th + 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 + specific bit to a 1, see . - The - PVR-list of the + 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 + 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 + 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 & + (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 + 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 @@ -2998,7 +2998,7 @@ 2 - ibm,change-msi busy: If set, the client program supports RTAS + ibm,change-msi busy: If set, the client program supports RTAS ibm,change-msi returning a -2 (Call again) or 990x (Extended delay) @@ -3081,7 +3081,7 @@ 2 - 64 bit PE TCEs : If set, the client program supports ibm,query-pe-dma-window + 64 bit PE TCEs : If set, the client program supports ibm,query-pe-dma-window returning a 64-bit value for PE TCEs @@ -3143,10 +3143,10 @@ ibm,dynamic-reconfiguration-memory: If set the client - program supports the - “ibm,dynamic-reconfiguration-memory” + 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 shall be represented with individual memory nodes. @@ -3206,10 +3206,10 @@ 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). + H_MIGRATE_DMA for >4K I/O pages and >256 xlates). See . - In the - ibm,architecture-vec-5 property of the + 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). @@ -3222,11 +3222,11 @@ On input to ibm,client-architecture-support this field shall be zero. - In the - ibm,architecture-vec-5 property of the + 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. + migration operation as: 256 * 2**N. See . @@ -3237,11 +3237,11 @@ On input to ibm,client-architecture-support this field shall be zero. - In the - ibm,architecture-vec-5 property of the + 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. + options supported as: 2**N. See . @@ -3301,9 +3301,9 @@ 0 - = the “Form value” of the - “ibm,associativity” and - “ibm,associativity-reference-points” + = the “Form value” of the + “ibm,associativity” and + “ibm,associativity-reference-points” properties. See for further details. @@ -3338,7 +3338,7 @@ Enable MTT Option - See + See . @@ -3396,7 +3396,7 @@ 7 - Reserved for Expansion + Enable Hash Page Table Resize Option @@ -3582,12 +3582,12 @@ 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” + 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. @@ -3596,12 +3596,12 @@ 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 + 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. @@ -3792,8 +3792,8 @@
Notes: - - + + The Ignore Policy bit indicates that the client program assumes all responsibility for the options represented by the option vector. The @@ -3803,7 +3803,7 @@ 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 @@ -3816,30 +3816,30 @@ 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 @@ -3847,34 +3847,34 @@ 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 + 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 @@ -3884,21 +3884,21 @@ 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 + 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., + (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 @@ -3911,7 +3911,7 @@ 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 @@ -3923,88 +3923,88 @@ 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 + Standard property name that denotes a ROM Node. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this property shall be + The value of this property shall be “rom”. - + “reg” [S] - Standard + Standard property name to define a unit-address for the node. prop-encoded-array: One ( phys-addr, size) pair. - The + 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 + 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 + Standard property name to define the address space representation of child nodes. - prop-encoded-array: an integer, encoded as with + prop-encoded-array: an integer, encoded as with encode-int. Its value shall be identical to that of - this node’s parent’s + this node’s parent’s “#address-cells” value. - + “ranges” [S] - Standard + Standard property name to define the address range that is - decoded by this + decoded by this /rom node. prop-encoded-array: One ( - child-phys, - parent-phys, - size) triple, where - child-phys equals + child-phys, + parent-phys, + size) triple, where + child-phys equals parent-phys and the number of cells of each - corresponds to the parent’s + corresponds to the parent’s “#address-cells” value. - + “available” [S] @@ -4012,35 +4012,35 @@ property name to define available ROM resources. - prop-encoded-array: Arbitrary number of - phys-addr, size pairs. + prop-encoded-array: Arbitrary number of + phys-addr, size pairs. Phys- - addr is a + 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 + 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 + prop-encoded-array: a string, encoded as with + encode-string, where the value could equal + “flash”, + “eeprom”, + “rom” or “nvram”. - + “cacheable” [S] @@ -4052,20 +4052,20 @@ - +
- +
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 + 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 + The following methods must be defined by /rom node. - + open (-- true) [M] @@ -4073,56 +4073,56 @@ Standard method to prepare the ROM Node for subsequent use. - + close (--) [M] Standard method to close the previously opened ROM Node. - + - decode-unit + decode-unit (addr len -- phys.lo...phys.hi) [M] Standard method to convert text unit-string to physical address. - + - encode-unit + 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 + The probe method for ROM Nodes shall probe for FCode - images within the address space defined by its + 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 + 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 + 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 + 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 + 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 @@ -4130,30 +4130,30 @@ - +
- +
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 + + The following properties must be created by /rom child nodes. - + “name” [S] - Standard + Standard property name that denotes a ROM child node. - prop-encoded-array: A string, encoded as with + 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 @@ -4161,44 +4161,44 @@ 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 + 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 + 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 + when the FCode evaluation for the node does not result in a “name” property being defined. - + “reg” [S] - Standard + 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 + 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 + + The following methods must be defined by /rom child nodes. @@ -4206,53 +4206,53 @@ open (-- true) [M] Standard method to prepare this device for subsequent use. - The - open method must be prepared to parse + 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 + 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 + 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 + + 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 + properties and methods for the RTAS node. The RTAS Node shall not have + “reg” or “ranges” properties.
RTAS Node Properties - - This section describes the + + This section describes the rtas node properties. @@ -4262,13 +4262,13 @@ Standard property name that denotes the RTAS node. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this property shall be + The value of this property shall be “rtas”. - + “rtas-event-scan-rate” [S] @@ -4276,14 +4276,14 @@ property name that is the rate at which an OS should read indicator/sensor/error data - prop-encoded-array: An integer, encoded as with + 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] @@ -4292,20 +4292,20 @@ implemented. prop-encoded-array: An array of paired integers ( - token maxindex), each encoded as with + 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 + 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] @@ -4314,20 +4314,20 @@ implemented. prop-encoded-array: An array of paired integers ( - token maxindex), each encoded as with + 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 + 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] @@ -4335,14 +4335,14 @@ property name describes version information for the RTAS implementation. - prop-encoded-array: An integer, encoded as with + 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] @@ -4350,27 +4350,27 @@ property name is the size of the RTAS memory image. - prop-encoded-array: An integer, encoded as with + 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 + prop-encoded-array: An integer, encoded as with encode-int. - The value of this property shall be the + 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] @@ -4378,13 +4378,13 @@ property name identifies maximum size of an extended error log entry. - prop-encoded-array: An integer, encoded as with + 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] @@ -4392,7 +4392,7 @@ property name specifies a future power on time capability. - prop-encoded-array: An integer, encoded as with + 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 @@ -4401,7 +4401,7 @@ days. - + “ibm,preserved-storage” @@ -4416,7 +4416,7 @@ LMBs and deregister the LMBs for preservation. - + “ibm,scan-log-directory” @@ -4427,73 +4427,73 @@ 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 + 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 + 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 + 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 + 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 + 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 + 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” @@ -4502,11 +4502,11 @@ prop-encoded-array: a character, NULL (0x00) if form-feed is not supported and np (0x0C) if form-feed is supported, - encoded as with + encoded as with encode-int. - + “ibm,environmental-sensors” @@ -4514,11 +4514,11 @@ which are available to an application. prop-encoded-array: An array of paired integers - (token maxindex), each encoded as with + (token maxindex), each encoded as with encode-int. - + “ibm,flash-block-version” @@ -4527,13 +4527,13 @@ /rtas node indicates the block list format to be used. - prop-encoded-array: integer encoded as with + 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] @@ -4541,13 +4541,13 @@ this platform. prop-encoded-array: List of (errinjct-token-name, errinjct-token-value) specifications. - errinjct-token-name: A string, encoded as with + errinjct-token-name: A string, encoded as with encode-string. - errinjct-token-value: is encoded as with + errinjct-token-value: is encoded as with encode-int. - + “ibm,lrdr-capacity” @@ -4556,7 +4556,7 @@ capabilities of the partition prop-encoded-array: A triple consisting of phys, - size, and one integer encoded as with + 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 @@ -4571,45 +4571,45 @@ not define a second integer for new purposes. - + “ibm,hypertas-functions” - property name of the + 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 + 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 + 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 + 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 + as with encode-int. - + “ibm,max-associativity-domains” @@ -4618,13 +4618,13 @@ 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 + 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” @@ -4632,7 +4632,7 @@ property name to specify that the partition was rebooted in the forced fire hose dump mode. - prop-encoded-array: An integer encoded as with + 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 @@ -4647,7 +4647,7 @@ program to save appropriate data and shutdown the partition. - + “ibm,integrated-stop-self” @@ -4659,7 +4659,7 @@ prop-encoded-array: NULL - + “ibm,rks-hcalls” @@ -4670,10 +4670,10 @@ provide that semantic. prop-encoded-array: A one to N byte bit vector, bit - positions representing hcall()s (see + 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 @@ -4768,7 +4768,7 @@
- + “ibm,reset-capabilities” @@ -4778,17 +4778,17 @@ RTAS call is implemented. prop-encoded-array: An integer encoded as with - encode-int that represents the functions supported in the + 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 + Functions 0 and 1 for the ibm,set-slot-reset RTAS call, when that RTAS call is implemented. - + “ibm,configure-kernel-dump-sizes” @@ -4803,7 +4803,7 @@ (not including any disk headers.) - + “ibm,configure-kernel-dump-version” @@ -4818,7 +4818,7 @@ firmware. - + “ibm,kernel-dump” @@ -4827,65 +4827,65 @@ 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 + 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 + input or output fields in the ibm,read-slot-reset-state2 RTAS call. If this - property does not exist, then the + 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 + 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 + 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 + Number Outputs of 5), as defined by . - Bit 31: When a value of 1, the + 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 + 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 + 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” @@ -4895,7 +4895,7 @@ sensor. - + “9001” @@ -4904,7 +4904,7 @@ indicator. - + “9002” @@ -4914,7 +4914,7 @@ hardware. - + “9003” @@ -4923,32 +4923,32 @@ “allocation-state” indicator. - + “ibm,extended-os-term” property-name indicating that the platform supports - extended - ibm,os-term behavior as described in + 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 - . + 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 + 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 @@ -4956,78 +4956,78 @@ 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 + 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 + 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 + property corresponding to that function name. See the for more information about RTAS functions. - + “ibm,termno” - property name of the + 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 + 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 + prop-encoded-array: List of Hypervisor-RTAS-function-set specifications. - Each + Each Hypervisor-RTAS-function-set specification is a byte - string encoded as with + string encoded as with encode-string. - +
- +
RTAS Node Methods - - The - instantiate-rtas or + + 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 + the ibm,client-architecture-support root node method, and - that method has not been called prior to the call of the - instantiate-rtas or + 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 + 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. @@ -5035,46 +5035,46 @@ instantiate-rtas (rtas-base-address -- rtas-call) [M] - Invoking the + Invoking the instantiate-rtas method binds the RTAS environment to a given location in System Memory and initializes the RTAS environment. - The in parameter, + 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 + 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 + 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, + 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 + 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 + 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. - +
- +
@@ -5087,11 +5087,11 @@ ibm,pft-size property name of the children of type - “cpu” of the + “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 + 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 @@ -5099,39 +5099,39 @@ 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 + 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: + 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-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. @@ -5148,13 +5148,13 @@ 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 + in the range of 0 to 2“ibm,interrupt-server#-size” - encoded as with + 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 + presented in the “ibm,ppc-interrupt-server#s” property and deactivated in the reverse order. @@ -5170,15 +5170,15 @@ 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 + 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 + encoded as with encode-int that specifies the global server queue that also may present interrupts to the interrupt management area - associated with the + associated with the server#. @@ -5204,17 +5204,17 @@ - +
- +
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. @@ -5224,7 +5224,7 @@ 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 + to #1. Presence of ibm,set-eeh-option RTAS call denotes platforms that support this level of functionality.) @@ -5234,13 +5234,13 @@ 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 + 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” @@ -5252,12 +5252,12 @@ 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 + 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 + 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. @@ -5272,17 +5272,17 @@ 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 + 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 + 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 + 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 @@ -5293,20 +5293,20 @@ “ibm,#dma-size-cells” property name to define the package’s dma - address + address size format. - prop-encoded-array: number encoded as with + 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 + encode the size field of ibm dma-window properties. If the “ibm,#dma-size-cells” property is - missing, the default value is the + missing, the default value is the “#size-cells” property for the package. - If both the - “ibm,#dma-size-cells” and + If both the + “ibm,#dma-size-cells” and “#size-cells” properties are missing, - refer to the - “#size-cells” property definition in the + refer to the + “#size-cells” property definition in the for the default value. @@ -5316,30 +5316,30 @@ property name to define the package’s dma address format. - prop-encoded-array: number encoded as with + 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 + encode the physical address field of ibm dma-window properties. If the “ibm,#dma-address-cells” property is - missing, the default value is the + missing, the default value is the “#address-cells” property for the - package. If both the - “ibm,#dma-address-cells” and + package. If both the + “ibm,#dma-address-cells” and “#address-cells” properties are missing, - refer to the + refer to the “#address-cells” property definition in - the + 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 + are added or modified for an LoPAR implementation. Refer to for the base PCI properties and - methods. For each platform PCI Host Bridge, a + methods. For each platform PCI Host Bridge, a “reg” property shall be present in the respective PCI Node. @@ -5350,32 +5350,32 @@ 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: + 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-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 + + 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 + accordance with . Each PCI PHB Node shall have - a Unit Address defined in the + 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 + 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 + Each PHB shall also have the “used-by-rtas” property, since RTAS is used for PCI Configuration. @@ -5392,11 +5392,11 @@ 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 + 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 + “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 @@ -5404,7 +5404,7 @@ Platform Architecture.) - + “model” [S] @@ -5413,26 +5413,26 @@ 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: + configuration registers: “vendor-id”, “device-id”, and “revision-id”. - prop-encoded-array: Text string, encoded as with + 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 + 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: + the standard PCI configuration registers: “vendor-id”, “device-id”, and “revision-id”. - + “64-bit-addressing” [S] @@ -5440,11 +5440,11 @@ 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 + addressing more than 4 GB of memory (required for all PHB nodes). - + “external-control” [S] @@ -5458,38 +5458,38 @@ 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 + 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 + 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 + 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 + prop-encoded-array: Integer, encoded as with encode-int. - This property, when present (for example, see Requirement + 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 @@ -5497,7 +5497,7 @@ adapter. - + “ibm,extended-address” [S] @@ -5508,13 +5508,13 @@ 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 + prop-encoded-array: 2 integers encoded with encode-int The first integer represents the maximum PCI Express lane-width at the Partitionable Endpoint. @@ -5525,37 +5525,37 @@ 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 + 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 + 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 + 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. @@ -5570,7 +5570,7 @@ prop-encoded-array: None. - + “266mhz-capable” [S] @@ -5580,7 +5580,7 @@ prop-encoded-array: None. - + “533mhz-capable” [S] @@ -5590,7 +5590,7 @@ prop-encoded-array: None. - + “ibm,msi-ranges” @@ -5608,15 +5608,15 @@ 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 + 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 + numbers, encoded as with encode-int. - + “ibm,msi-x-ranges” @@ -5634,14 +5634,14 @@ 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 + 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” @@ -5650,11 +5650,11 @@ 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 + encoded as with encode-int. - + “ibm,req#msi-x” @@ -5664,47 +5664,47 @@ than the number of MSI-X interrupts actually assigned by the firmware. prop-encoded-array: number of requested MSI-X - interrupts encoded as with + 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 + prop-encoded-array: the concatenation, with encode+, of an arbitrary number of text strings, - each encoded as with + 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 + connectors specified in “ibm,connector-type”. If this property - is provided in the same node with an + 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 + 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 + prop-encoded-array: the concatenation, with encode+, of an arbitrary number of text strings, - each encoded as with + each encoded as with encode-string. - + “ibm,pci-config-space-type” @@ -5715,26 +5715,26 @@ configuration address space accesses. 1 = Platform supports a twelve bit register number for configuration address space accesses. - This property may be provided in all + 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 + 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 + prop-encoded-array: Text string, encoded as with encode-string. - The property value, when present, can have the values specified in + The property value, when present, can have the values specified in . - + Values <emphasis role="bold"><literal>“ibm,reserved-explanation”</literal></emphasis> @@ -5780,7 +5780,7 @@
- + “ibm,pe-total-#msi” @@ -5788,14 +5788,14 @@ 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 + be obtained by Function 0 (Query only) of the ibm,change-msi RTAS call. prop-encoded-array: Maximum number of interrupts - encoded as with + encoded as with encode-int. - + “ibm,ehci-boot-supported” @@ -5804,27 +5804,27 @@ 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 + 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 + 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 @@ -5834,22 +5834,22 @@ 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 + 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 + 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 + 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 + 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 @@ -5868,13 +5868,13 @@ 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. + 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 @@ -5883,7 +5883,7 @@ prop-encoded-array: <none> - + ibm,h-get-dma-xlates-limited-supported @@ -5893,12 +5893,12 @@ - +
- +
LPAR Option Properties - + “ibm,dma-window” @@ -5906,21 +5906,21 @@ property name to define the bus address window children of this bridge may use for dma. prop-encoded-array: One ( - logical-bus-number, phys, + 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 + 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 + 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 + 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 + 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 @@ -5929,7 +5929,7 @@ referenced. - + “ibm,is-vf” @@ -5937,7 +5937,7 @@ 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 @@ -5990,18 +5990,18 @@ - + - + - + - +
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 @@ -6009,52 +6009,52 @@ 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 + 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 + 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: + 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-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 + + 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 + logical memory block with its own /memory node. Any new memory granted to an OS image - is done so with a new + 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 + full blocks represented by one of its currently held /memory nodes. - The value of + 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 + The “ibm,my-drc-index” property as defined in - + . @@ -6064,33 +6064,33 @@ 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 + 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 + 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 + 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. 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. @@ -6100,7 +6100,7 @@ contents have not been preserved. - + “ibm,expected#pages” @@ -6108,17 +6108,17 @@ the client program is expected to use to virtually map the LMB represented by this node. - prop-encoded-array: An integer encoded as with + 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 + 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 @@ -6126,20 +6126,20 @@ - +
- +
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 + 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 + address or “reg” property. The following properties are defined. @@ -6149,83 +6149,83 @@ property name that defines the size of each dynamically reconfigurable LMB. - prop-encoded-array: An integer encoded as with + 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 + find the ibm,associativity-array property value for the LMBs. prop-encoded-array: The number M of associativity - lists encoded as with + lists encoded as with encode-int, the number N of entries per - associativity list encoded as with + associativity list encoded as with encode-int, followed by M associativity lists each - of length N integers encoded as with + of length N integers encoded as with encode-int. - This property is used to duplicate the function of the - “ibm,associativity” property in a + 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 + 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 + reported by the ibm,configure-connector RTAS function is a /memory - node, with the inclusion of the + node, with the inclusion of the “ibm,associativity” device tree property - defined in + 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 + 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 + 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 + 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 + 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” + 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 + list corresponds to the + “ibm,associativity” property in a /memory device tree node. - A flags word, encoded as with + 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 + 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 @@ -6252,10 +6252,10 @@ 0x00000001 - If b'0', corresponds to the + If b'0', corresponds to the “ibm,preserved” property having a zero value. - If b'1', corresponds to the + 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. @@ -6269,10 +6269,10 @@ 0x00000002 - If b'0', corresponds to the + If b'0', corresponds to the “ibm,preservable” property having a zero value. - If b'1', corresponds to the + If b'1', corresponds to the “ibm,preservable” property having a non-zero value. @@ -6285,10 +6285,10 @@ 0x00000004 - If b'0', corresponds to the + If b'0', corresponds to the “ibm,preserved” property having a 0x1 value. - If b'1', corresponds to the + 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”). @@ -6315,11 +6315,11 @@ 0x00000010 - If b'0', corresponds to non-existence of the - “ibm,no-h-migrate-dma” in the + 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 + If b'1', corresponds to existence of the + “ibm,no-h-migrate-dma” in the memory node. @@ -6331,15 +6331,15 @@ 0x00000020 - If b'0', the DRC field of + 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” + is valid or the DRC values for the set of + “ibm,dynamic-memory-v2” property are valid. - If b'1', the DRC field of + 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” + is invalid or the DRC values for the set of + “ibm,dynamic-memory-v2” property are invalid. @@ -6351,10 +6351,10 @@ 0x00000040 - If b'0', the Associativity List Index field of + 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 + If b'1', the Associativity List Index field of “ibm,dynamic-memory” property or “ibm,dynamic-memory-v2” is invalid. @@ -6367,10 +6367,10 @@ 0x00000080 - If b'0', corresponds to the + If b'0', corresponds to the “status” property having a value of “okay”. - If b'1', corresponds to the + If b'1', corresponds to the “status” property having a value of “reserved”. @@ -6392,62 +6392,62 @@
- + “ibm,dynamic-memory-v2” - + - property name that defines memory subject to dynamic + 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, + encode-int, followed by N LMB set entries. - - The number-of-sequential-lmbs encoded with - encode-int. + + 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 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 starting-drc-index encoded with + encode-int. The drc-index of the first LMB in the set. - - The associativity-index encoded with - encode-int. + + 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 + + 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 + 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 + appear in the “ibm,preservable” property in the old bindings for a preservable LMB. - prop-encoded-array: An integer value encoded as with + 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 @@ -6458,40 +6458,40 @@
- +
- +
Memory Controller Nodes - This section describes + This section describes memory-controller nodes and their properties. NUMA - configurations, have multiple + configurations, have multiple memory-controller nodes in the device tree one for each Central Electronics Complex (CEC). In dynamic reconfiguration NUMA - environments, these + 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 + + 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 + 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 + “/” (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 + 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 + A Memory Controller can also have the + “used-by-rtas” property (see ), if it has functions abstracted by RTAS. @@ -6501,13 +6501,13 @@ Standard property name that denotes a Memory Controller node. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this property shall be + The value of this property shall be “memory-controller”. - + “reg” [S] @@ -6515,22 +6515,22 @@ 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 + 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 + 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 @@ -6538,7 +6538,7 @@ more information.) - + “external-control” [S] @@ -6553,146 +6553,146 @@ 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 + prop-encoded-array: a string, encoded as with encode-string, where the value could equal “none”, “ecc”, or “parity”. - The value of + The value of “#address-cells” for this node is 1. - The value of + 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 + 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 + No nodes of type IBM,memory-module shall be defined anywhere in the - device tree when the platform supports dynamic VPD via the RTAS + 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 + normally be reported via the “ibm,vpd” property in these nodes shall - be reported by + be reported by ibm,get-vpd. - +
Properties for Memory Modules - - Memory modules appear as children of the + + Memory modules appear as children of the memory node or, for platforms supporting memory DR - operations (either logical or physical), the + operations (either logical or physical), the memory-controller node of the device tree. This - section defines properties for the + section defines properties for the IBM,memory-module nodes and additional properties for - the - memory and + the + memory and memory-controller nodes. - +
- +
<literal>IBM,memory-module</literal> Node Properties - - An - IBM,memory-module node is a child of the + + An + IBM,memory-module node is a child of the memory node or, for platforms supporting memory DR - operations (either logical or physical), the + operations (either logical or physical), the memory-controller node. - The + The “name” of the node is “IBM,memory-module” - The + The “device_type” of the node is “IBM,memory-module” - The + The “reg” - standard property for an + standard property for an IBM,memory-module node is its memory module number which is an arbitrary OF selected enumeration. - The + The “ibm,size” - property for an + 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 + 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 + 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 + 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 + the module, in bytes. The property “ibm,size-upper” is not required if the memory module size is less than 4GB. - The + The “status” - standard property for an + 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 + “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. - + @@ -6701,72 +6701,72 @@ property name defines the number of memory banks contained within the memory module. - prop-encoded-array: an integer, encoded as with + 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 + prop-encoded-array: a string, encoded as with encode-string, that describes the type of module, - with values of + with values of “FP” (Fast Page), - “EDO” (Extended Data Out), or + “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 + 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 + 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 + 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 + 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 @@ -6790,17 +6790,17 @@ property name that denotes a PowerPC External Interrupt Domain - prop-encoded-array: An integer encoded as with + prop-encoded-array: An integer encoded as with encode-int. - +
PowerPC External Interrupt Presentation Controller Node Properties - + The following properties apply to this node. @@ -6810,26 +6810,26 @@ Standard property name that denotes a PowerPC External Interrupt Controller. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + 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 + prop-encoded-array: A string, encoded as with encode-string. - The value of this property shall be + The value of this property shall be “PowerPC-External-Interrupt-Presentation”. - + “reg” [S] @@ -6842,36 +6842,36 @@ phys-addr, size ) specifications. - Phys-addr is encoded as with - encode-phys, and - size is encoded as with + 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 + entries in the “ibm,interrupt-server-ranges” property described below. - + “compatible” [S] Standard - property name to define alternate + property name to define alternate “name” property values. - prop-encoded-array: The concatenation, with + prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, - each encoded as with + each encoded as with encode-string. - The property value shall include + The property value shall include “IBM,ppc-xicp”. - + “ibm,interrupt-buid-size” @@ -6879,41 +6879,41 @@ implemented in the concatenation of the BUID fields. prop-encoded-value: An integer in the range of 9 to - 20 encoded as with + 20 encoded as with encode-int. As platforms grow in size so as to require use of larger BUIDs - (values of the + (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 + 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 + 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 + 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 + The range shall be the number of contiguous server# s supported by the unit (this also - corresponds to the number of + corresponds to the number of “reg” entries). - + “interrupt-controller” [S] @@ -6925,7 +6925,7 @@ controller. - + “model” [S] @@ -6933,7 +6933,7 @@ property name indicating this unit’s manufacturer, part number, and revision level. - prop-encoded-array: Text string, encoded as with + 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 @@ -6942,19 +6942,19 @@ - +
- +
PowerPC External Interrupt Source Controller Node Properties - - Interrupt source controller resources as represented by - “interrupt-ranges”, - “#interrupt-cells”, and + + 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 + other logical equivalent nodes which contain the “interrupt-controller” property. The following properties apply to these nodes. @@ -6965,20 +6965,20 @@ Standard property name that denotes a PowerPC External Interrupt Controller. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + 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 + prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be one of the following: “PowerPC-LSI-Source” @@ -6988,7 +6988,7 @@ with PCI MSI. - + “reg” [S] @@ -6997,34 +6997,34 @@ 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 + Phys-addr is encoded as with + encode-phys, and + size is encoded as with encode-int. - If the + If the “device-type” of the interrupt source - controller is - “PowerPC-MSI-Source”, then the last + 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 + property name to define alternate “name” property values. - prop-encoded-array: The concatenation, with + prop-encoded-array: The concatenation, with encode+, of an arbitrary number of text strings, - each encoded as with + each encoded as with encode-string. - The property value shall include + The property value shall include “ibm,ppc-xics”. - + “interrupt-ranges” [S] @@ -7033,21 +7033,21 @@ and range(s) handled by this unit. prop-encoded-array: List of ( int-number, range) specifications. - Int-number is encoded as with + Int-number is encoded as with encode-int. - Range is encoded as with + 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 + 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] @@ -7059,14 +7059,14 @@ controller. - + “model” [S] Standard property name indicating this unit’s manufacturer, part number, and revision level. - prop-encoded-array: Text string, encoded as with + 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 @@ -7074,26 +7074,26 @@ dependent (see the Core document for more information). - + “#interrupt-cells” [S] - Standard property name to define the number of cells in an + 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 + 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 + 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 + 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” @@ -7101,43 +7101,43 @@ 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 + 24 encoded as with encode-int. As platforms grow in size so as to require use of the - server#extension field (values 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 + 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. @@ -7154,7 +7154,7 @@ ‘riser’ cards. - + “used-by-rtas” [S] @@ -7166,10 +7166,10 @@ - - The use of the + + The use of the “slot-names” property defined below is - deprecated in favor of the + deprecated in favor of the “ibm,loc-code” property. @@ -7178,9 +7178,9 @@ property name: Describes external labeling of adapter/device connectors. - prop-encoded-array: An integer, encoded as with + prop-encoded-array: An integer, encoded as with encode-int, followed by a list of strings, each - encoded as with + 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 @@ -7195,35 +7195,35 @@ 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 + encoded as with encode-string. - + “ibm,vpd” property name to provide Vital Product Data (VPD) - information as defined in + information as defined in . - prop-encoded-array: the concatenation, with + 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 + 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” @@ -7231,10 +7231,10 @@ 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 + 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 + 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 @@ -7243,24 +7243,24 @@ - +
- +
- +
<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 + + 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 + following aliases as properties of the aliases node, if the corresponding device exists: @@ -7270,7 +7270,7 @@ property name indicating the device path of the factory default disk that is the preferred boot disk - Implementation Note: The preferred + 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 @@ -7424,14 +7424,14 @@ - +
- +
<literal>/event-sources</literal> Node - The + The /event-sources node describes the possible RTAS Error - and Event Classes for interrupts. The + 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: @@ -7442,15 +7442,15 @@ Standard property name that denotes the Event Sources. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + The value of this string shall be “event-sources”. When events are reported as virtual interrupts there shall be a - node of + node of device_type “PowerPC-External-Interrupt-Presentation” from - which the virtual interrupt source BUID size can be obtained. Also the + 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: @@ -7465,7 +7465,7 @@ prop-encoded-array: <none> The presence of this property indicates that this node represents a source of virtual - interrupts. Encoded with + interrupts. Encoded with encode-null. @@ -7473,8 +7473,8 @@ “#interrupt-cells” [S] - Refer to the definition of the - “#interrupt-cells” property for nodes of + 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. @@ -7484,9 +7484,9 @@ “interrupt-ranges” [S] - Refer to the definition of the + Refer to the definition of the “interrupt-ranges” property for nodes of - device_type + device_type “PowerPC-LSI-Source” for information about the definition of this property for virtual event interrupts. @@ -7504,24 +7504,24 @@
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 + Children of the /event-sources node specify the interrupt specifiers associated with the reporting of platform events. Interrupt designs shall - use the 1275 standard + use the 1275 standard “interrupts” property as configured to report the interrupt specifier for the platforms PowerPC interrupt - controller. The interrupt specifiers if the + 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. @@ -7533,20 +7533,20 @@ property name that denotes the internal error’s events. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + 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. @@ -7556,19 +7556,19 @@ Standard property name that denotes the EPOW events. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + 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. @@ -7579,22 +7579,22 @@ property name that denotes the I/O sub-system events. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + 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 + + The presence of the node indicates that all or some of the function has been implemented and will be reported using an interrupt. @@ -7605,22 +7605,22 @@ property name that denotes the hot-plug events. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + The value of this string shall be “hot-plug-events”. - +
- +
<literal>/reserved</literal> Node - - This section defines a reserved node which shall have a + + 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 @@ -7633,9 +7633,9 @@ Standard property name that denotes reserved addresses that do not belong to a recognized device. - prop-encoded-array: A string, encoded as with + prop-encoded-array: A string, encoded as with encode-string. - The value of this string shall be + The value of this string shall be “reserved”. @@ -7643,12 +7643,12 @@ “device_type” [S] - Standard + Standard property name that indicates the device type. - prop-encoded-array: Text string, encoded as with + prop-encoded-array: Text string, encoded as with encode-string. - The value of this property shall be + The value of this property shall be “reserved”. @@ -7662,11 +7662,11 @@ 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 + to #address-cells, encoded as with encode-phys. - size is a sequence equal to - #size-cells encoded as with + 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 ( @@ -7676,28 +7676,28 @@ - +
- +
<literal>/chosen</literal> Node - - This section lists additional properties as required under the + + This section lists additional properties as required under the /chosen node with the following text in a manner that - is consistent with + is consistent with , Section 3.5. “nvram” [S] - Standard property name that defines the package + 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 + 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 + 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. @@ -7710,7 +7710,7 @@ the client program’s IBM,RPA-Client-Config ELF note section. prop-encoded-array: an array of integers encoded as - with + with encode-int, that consist of the fields of the note section that the firmware processed prior to loading the client program. @@ -7721,12 +7721,12 @@ “ibm,architecture-vec-5” property name: that presents the values of the - option vector #5 negotiated by 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 + 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 + format of the fifth option vector from representing the value chosen by the ibm,client architecture-support method. @@ -7737,33 +7737,33 @@ 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 + 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 + 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 + 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 + 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 + associated with the /vdevice node have special values as specified below. @@ -7771,8 +7771,8 @@ “#address-cells” [S] - Standard - property name encoded as with + 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. @@ -7781,8 +7781,8 @@ “#size-cells” [S] - Standard - property name encoded as with + 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 @@ -7793,8 +7793,8 @@ “name” [S] - Standard - property name string encoded as with + Standard + property name string encoded as with encode-string that defines the name of node. The value shall be the string “vdevice”. @@ -7803,8 +7803,8 @@ “device_type” [S] - Standard - property name string encoded as with + Standard + property name string encoded as with encode-string that defines the device type of the node. The value shall be the string “vdevice”. @@ -7813,7 +7813,7 @@ “ibm,max-virtual-dma-size” - Vendor unique + 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 @@ -7838,7 +7838,7 @@ “ibm,reserved-virtual-addresses” - Vendor unique + Vendor unique property name indicating ranges of the client program virtual address space that are reserved for platform use. @@ -7847,28 +7847,28 @@ representing the origin and length respectively of a reserved virtual address range. abbreviated-virtual-address: Consists of two integers - encoded as with + 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 + 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 + + The children of the /vdevice node represent the individual virtual devices. - Children of the + Children of the /vdevice node that support dma operations contain a - the + the “ibm,my-dma-window” property as defined below: @@ -7880,47 +7880,47 @@ that this IOA may use for its dma. prop-encoded-array: One or more ( - logical-I/O-bus-number, phys, + 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 + 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 + 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 + The “ibm,my-dma-window” property is the per - device equivalent of the + device equivalent of the “ibm,dma-window” property found in nodes representing bus bridges. - Children of the + 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 + 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 + Children of the /vdevice node which act a a server to other virtual client devices, display the following property. - + “ibm,vserver” @@ -7930,18 +7930,18 @@ 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 + encoded as with encode-int. - + “ibm,trunk-adapter” @@ -7951,7 +7951,7 @@ property. - + “ibm,illan-options” @@ -7963,13 +7963,13 @@ 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” + 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. @@ -7979,7 +7979,7 @@ “ibm,vnic-mode” - Vendor unique property name that represents the operational + 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. @@ -8001,7 +8001,7 @@ “ibm,vnic-client-mac” - Vendor unique property name that represents the 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. @@ -8013,14 +8013,14 @@ 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 + 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 + presented in the “ibm,termno” property. Such virtual - terminals, as represented by the + terminals, as represented by the “ibm,termno” property, are intended for - the use of the client program and shall not be marked + 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. @@ -8028,47 +8028,47 @@ “name” [S] - Standard - property name encoded as with + Standard + property name encoded as with encode-string that defines the device name. The value - shall be the string + 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, 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 + (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 + Standard property name encoded as with encode-string to specify the device type. The value - shall be the string + shall be the string “serial” indicating that the device emulates a serial terminal. - + “compatible” [S] - Standard - property name encoded as with + Standard + property name encoded as with encode-string to specify the device driver - compatibility. The value shall be one of the strings specified in + compatibility. The value shall be one of the strings specified in . - + Virtual tty compatibility strings @@ -8126,63 +8126,63 @@
- See + See for further detail on this virtual device. - +
- +
- Children of + <title>Children of <literal>/vdevice</literal> node defined in other documents - - Like children of the pci bus node, children of + + 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 + children of /vdevice. Examples include NVRAM and Real Time Clock - (RTC) devices which are defined by + (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 + 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 + 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 + reconfiguration will add properties per requirements called out in the . “name” [S] - Standard - property name encoded as with + 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 + shall be the string + “ibm,bsr” for legacy implementations and “ibm,bsr2” for POWER8 implementations and beyond. @@ -8191,16 +8191,16 @@ “reg” [S] - Standard + 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 + 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 + the window. The + size, encoded in the number of cells specified by “#size-cells” of the parent, is the length of the corresponding window. @@ -8209,10 +8209,10 @@ “device_type” [S] - Standard - property name encoded as with + Standard + property name encoded as with encode-string to specify the device type. The value - shall be the string + shall be the string “ibm,bsr”. @@ -8220,10 +8220,10 @@ “compatible” [S] - Standard - property name encoded as with + Standard + property name encoded as with encode-string to specify the device driver - compatibility. The value shall be the string + compatibility. The value shall be the string “ibm,bsr”. @@ -8235,7 +8235,7 @@ 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 + 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. @@ -8248,8 +8248,8 @@ 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 + 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 @@ -8257,16 +8257,16 @@ - +
- +
- Nodes of device_type <literal>“block”</literal> and + <title>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 + without a “reg” property. @@ -8292,18 +8292,18 @@ - +
- +
<literal>/ibm,platform-facilities</literal> - - The node of type + + 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 + associated with the /ibm,platformfacilities node have special values as specified below. @@ -8311,7 +8311,7 @@ “#address-cells” [S] - Standard + 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 @@ -8322,8 +8322,8 @@ “#size-cells” [S] - Standard - property name encoded as with + 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 @@ -8334,10 +8334,10 @@ “name” [S] - Standard - property name string encoded as with + Standard + property name string encoded as with encode-string that defines the name of node. The - value shall be the string + value shall be the string “ibm,platform-facilities”. @@ -8345,28 +8345,28 @@ “device_type” [S] - Standard - property name string encoded as with + Standard + property name string encoded as with encode-string that defines the device type of the - node. The value shall be the string + 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 + 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 + node of the + /ibm,platform-facilities node (). Additionally, the node representing the platform facilities Interrupt Source Controller shall - contain the + contain the “ibm,interrupt-pool” property, and all platform facilities that share the common pool of interrupts shall - contain the + contain the “ibm,shared-interrupt-pool” property. @@ -8376,7 +8376,7 @@ property name: that indicates this interrupt controller provides a shared pool of interrupt source numbers. - property encoded array: single cell encoded as with + 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. @@ -8390,193 +8390,193 @@ 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 + 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 + property encoded array: single cell encoded as with encode-int - +
Children of the <literal>/ibm,platform-facilities</literal> Node - - The children of the + + The children of the /ibm,platform-facilities node represent the individual platform facilities. Standard property names associated with - the children of the + the children of the /ibm,platform-facilities node have special values as - specified below. Note the children of the + 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 + “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 + + 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 + + + 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 + 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 + 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 + more cells each encoded as with encode-int. The interpretation of the series of - integers is unique per the value of the + 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 + property encoded array: single cell encoded as with encode-int - + “ibm,shared-interrupt-pool” @@ -8590,7 +8590,7 @@ - + For the memory utilization instrumentation facility node the following properties are defined: @@ -8601,7 +8601,7 @@ “ibm,mui-associativity-mapping” - property name to define the mapping between Memory Usage + 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. @@ -8610,25 +8610,25 @@ An integer (ALAentry) encoded as with encode-int - as would be found in the affinity_log record for the return buffer + 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 + 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 + (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, + 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 @@ -8645,15 +8645,15 @@ - An integer (N) encoded as with + 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 + Each associativity list consisting of a number of entries integer (P) encoded as with encode-int - followed by P integers encoded as with + followed by P integers encoded as with encode-int each representing an associativity domain number. @@ -8661,20 +8661,20 @@ - + “ibm,mui-ranges” - property name to define the implementation specific + 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 + + 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. + 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. @@ -8710,8 +8710,8 @@ MIN/MAX - The minimum and maximum supported value of the HUC field - which is the power of 2 multiplier of microseconds that defines the + 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. @@ -8745,7 +8745,7 @@ 0/MAX - Page Age; the MAX value is the number of Page Age Granules + Page Age; the MAX value is the number of Page Age Granules which saturates the page age counter. @@ -8764,59 +8764,59 @@
- +
- +
- +
Symmetric Multi-Processors (SMP) - + LoPAR platforms can have Symmetric Multi-Processor (SMP) - Configurations. In addition to the processor node properties defined in + Configurations. In addition to the processor node properties defined in , a SMP Configuration will - utilize the - /cpus node as explained in + utilize the + /cpus node as explained in - +
SMP Platform Device Tree Structure - + OF requires that multiple instances of any device that appears more than once in the device tree must be unique and distinguishable by means - of their + of their “reg” properties. For LoPAR platforms, processors shall not be directly attached to the main physical bus (root node (“ / ”)). Instead, cpu devices shall be children - of the + of the /cpus node. - The + The /cpus node shall have one child node of device type - cpu for each processor. The + cpu for each processor. The ihandle of the “executing” processor shall - be published in the - “cpu” property of the + be published in the + “cpu” property of the /chosen node. Note: The properties of a cpu device are already - defined in + defined in . The only change for symmetric multiprocessor (SMP) systems is that there will be a cpu device node - under the + under the /cpus node for each individual processor. Other properties of the cpu devices shall - conform with the requirements stated in + conform with the requirements stated in . - +
- +
SMP Properties - + The following properties are for a PA SMP environment. These SMP - properties will be under the + properties will be under the /cpus Node. @@ -8825,16 +8825,16 @@ property name that describes platform labeling of plug-in cpu/processor card slots. - prop-encoded-array: An integer, encoded as with + prop-encoded-array: An integer, encoded as with encode-int, followed by a list of strings, each - encoded as with + encoded as with encode-string. The integer portion of the property value is a bitmask of possible processors; for each add-in slot on the bus, the bit corresponding to that slot’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 slots; the first string gives the platform nomenclature - for the slot with the smallest ID number, and so on. The CPU’s + for the slot with the smallest ID number, and so on. The CPU’s “slot-names-index” property can be used as an index into the bitmask integer of this property. The absence of this property indicates that no slots are present. @@ -8852,14 +8852,14 @@ - +
- +
Processor Node - + The following properties are for a PA SMP environment. This SMP - property will be under each + property will be under each /cpu Node. @@ -8870,23 +8870,23 @@ property name: Identifies each cpu with a unique number. - prop-encoded-array: An integer, encoded as with + prop-encoded-array: An integer, encoded as with encode-int. The value of this integer is a platform unique number with a range - from 0 to - n-1 for each CPU where + from 0 to + n-1 for each CPU where n is the number of slots. This number is used to - index into the + index into the “slot-names” property to identify the value of the string associated with the slot name. - +
- +
- +
Device Power Management Properties/Methods This section defines standard platform node properties, device node @@ -8896,16 +8896,16 @@ OS providers who want to ensure that the data needed for their power management policies is included should contact the authors of this document. - +
System Node Properties - + The following defines properties are to be associated with the rtas and the power-management-events nodes of the device tree.
Properties assigned to the RTAS node - + Power domains are a feature of platforms which support power management. Within the OF device tree, power domains are represented by a power domain identifier which is defined to be an integer in the range 0 @@ -8915,12 +8915,12 @@ “power-domains-tree” [S] - Standard + Standard property name which defines the power domain hierarchy for this platform. prop-encoded-array: An array of integers, each - encoded as with + encoded as with encode-int, that is a flattened representation of the power domain dependency tree. The array consists of a number of tuples, one for each power domain @@ -8937,54 +8937,54 @@ devices within the particular power domain. - + “power-domains-controllers” [S] - Standard + Standard property name which defines the power domain controllers present on this platform. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int. - Each integer is the + Each integer is the phandle of the device tree node that functions as the power domain controller for a domain. A single controller may serve as the control point for multiple domains (the architecture calls them power domain control points). Each device which serves as a controller encodes - the + the “controls-power-domain” property. - + “power-domains-names” [S] - Standard + Standard property name used to define the user readable names for the power domains. prop-encoded-array: an array of strings, each - encoded as with + encoded as with encode-string, that are the user readable names for the domains. The number of strings matches the number of domains and there is a - one-to-one correspondence between the entries in the + one-to-one correspondence between the entries in the “power-domain-controllers” property and the entries in this array. - + “platform-power-sources” [S] - Standard + Standard property name defining the platform power sources. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int. The array is structured as a number of tuples. Each of these tuples consists of the values source-voltage, (given in millivolts), peak-power, @@ -8992,71 +8992,71 @@ stated voltage), and conversion-efficiency (expressed in percent). - + “power-sources-names” [S] - Standard + Standard property name defining the platform power source names. prop-encoded-array: an array of strings, each - encoded as with + encoded as with encode-string, that are the user readable names for the power sources. The number of strings match the number of power sources and is in - one-to-one correspondence to the entries in the + one-to-one correspondence to the entries in the “platform-power-sources” property. - + “platform-battery-sources” [S] - Standard + Standard property name defining the batteries utilized by a platform. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int. Each value in this array is the manufacturer’s rated capacity of the battery expressed in milliwatt-hours. - + “battery-sources-names” [S] - Standard + Standard property name defining the human-readable identifier of the batteries utilized by a platform. prop-encoded-array: an array of strings, each - encoded as with + encoded as with encode-string. Each entry in this array corresponds one-for-one with the batteries - defined in the + defined in the “platform-battery-sources” property. - +
- +
Properties of the power-management-events node - + “power-type” [S] - Standard + Standard property name defining the power management event types implemented on a specific platform. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int. @@ -9068,22 +9068,22 @@
Device Properties - + “power-domains” [S] - Standard + Standard property name, indicating the power domains of which this device is a member. - prop-encoded-array: List of one or more - domain-id’s to which this device belongs. - Domain-id’s is encoded as with + prop-encoded-array: List of one or more + domain-id’s to which this device belongs. + Domain-id’s is encoded as with encode-int. - The + The “power-domains” property should only list - the + the domain-id’s of the lowest power domain tree nodes in which this device has membership. If the device is a member of the default power domain 0 alone, this property does not need to be @@ -9094,12 +9094,12 @@ “device-power-states” [S] - Standard + Standard property name which describes the power states this device supports. prop-encoded-array: An array of integers, each - encoded as with + encoded as with encode-int that defines the supported power states for this device. This property shall be provided for each physical device which has @@ -9119,7 +9119,7 @@ the power source. The value state shall be further constrained to have the following semantics: - + Semantics of device state values @@ -9199,10 +9199,10 @@ The semantics of device power states may be further defined by device type specific bindings.The interaction of the defined semantics of device power state and - domain power level is defined in + domain power level is defined in . Those combinations not marked are disallowed. - +
Combinations of Device Power State/Domain Power Level @@ -9311,12 +9311,12 @@ “device-state-transitions” [S] - Standard + Standard property name that describes the legal power state transitions supported by the device. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int that defines the legal power state transitions for this device. The array is structured as a number of tuples, one for each @@ -9325,7 +9325,7 @@ (power-source-id, power), one for each power source, followed by the time required to make the transition in microseconds, followed by the maximum count allowed for this transition. The starting state and destination - state are values defined in the + state are values defined in the “device-power-states” property. The value power is stated in the millamperes consumed. This property shall be provided if platform firmware provides device power state @@ -9336,12 +9336,12 @@ “power-sources” [S] - Standard + Standard property name which designates this device as a consumer of power sourced from a defined power source. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int that gives the list of power sources to which this device is connected. The values are indices into the platform-power-sources data @@ -9353,12 +9353,12 @@ “power-management-mapping” [S] - Standard + Standard property name that defines device power states and commands. prop-encoded-array: an array of integers as encoded - with + with encode-int. This optional property provides a device dependent mapping between device power state and commands which the device driver sends to its @@ -9371,7 +9371,7 @@
Properties for Power Domain Control Points - + The following are specific to devices which can act as power domain control points. @@ -9379,12 +9379,12 @@ “controls-power-domains” [S] - Standard + Standard property name which designates the domains over which this device exercises control. prop-encoded-array: an array of integers, each - encoded as with + encoded as with encode-int that defines the domains for which this device can act a power domain control point. A single device may serve as multiple logical control @@ -9434,12 +9434,12 @@
- + - +
Configuration of Platform Resources - + Any computer platform is composed of standard components which are invariant (platform ‘built-in’ standard I/O and power management), optional components which are detectable (a second processor, @@ -9452,16 +9452,16 @@ A Platform shall also have the capability of configuring power management resources, if power management is implemented by the platform, - as defined in + as defined in . - +
Power Management Resource Configuration - + For a platform which supports device power management, all platform power management related information shall be resident in the OF device tree prior to the transfer phase of software operation (see the - definition of transfer phase in + definition of transfer phase in ). Dummy devices shall be placed in the device tree for all standard I/O bus connectors which are not in use to provide a node to assign the slot-names, power-domains, and @@ -9476,7 +9476,7 @@
Power Management Information Utility - + Any platform capable of being expanded via the addition of power-managed devices shall provide a device power management information utility. The purpose of the utility is to allow a person (end-user or @@ -9499,7 +9499,7 @@ device attached to the external scsi connector labeled ‘SCSI1’.” A data structure describing the subtree is stored in NVRAM. The - root node of this subtree contains an + root node of this subtree contains an “in-graft-node” property which specifies the path to the parent node where the subtree is to be grafted into the OF device tree. @@ -9509,28 +9509,28 @@ obtain this information without the need for this utility. Any information obtained by direct device interrogation may update that supplied via the PM NVRAM partition. - +
- +
PM Configuration Process - + When the platform is booted after a configuration change and the newly inserted adapter does not support the automatic reporting of power management information, firmware should prompt the user asking if he wishes to supply this information or potentially forfeit some or all of the power management capabilities of the device. The utility records the information it obtains in the NVRAM Power - Management Configuration Partition (NVRAM Signature of 0x71 and name + Management Configuration Partition (NVRAM Signature of 0x71 and name pm-config). On a subsequent reboot, platform firmware uses the information saved in NVRAM to fill out the device tree adding new nodes and their properties, as well as adding properties and updating the values of properties of existing device tree nodes. - +
PM Configuration Format - + The NVRAM power management configuration partition is designed to be accessed primarily by firmware, but the partition is designated global and the format is specified to allow a third party to write a power @@ -9548,7 +9548,7 @@ list area locates the start of a NULL-terminated string which represents a list of property name/value pairs. The following table specifies the format of the header: - +
Power Management Configuration Data Header @@ -9627,7 +9627,7 @@
The PM Partition data area format value shall be 1. The following table specifies the format of the data blocks: - + Data Block Format @@ -9686,7 +9686,7 @@ The data block type field shall have the value 1 for a data block which describes a device node. The data block type field shall have a value 2 for a data block which describes a property. - +
Node Data Block Format @@ -9776,7 +9776,7 @@
- + Property Data Block Format @@ -9853,9 +9853,9 @@
- The first node of a subtree shall have a + The first node of a subtree shall have a “name” property equal to “/” - and shall specify the + and shall specify the “in-graft-node” property. The child_ptr of this data block points to the first in a list of data blocks which describe the nodes which make up the subtree to be grafted onto the @@ -9864,40 +9864,40 @@ which represent property name/value pair lists. The last string in this area will be terminated by at least two NULL bytes. The property list for each node shall provide all the required PM properties and their values. - These include - “power-domains”, - “device-power-states”, - “device-state-transitions”, - “power-sources”, - “power-management-mapping”, and + These include + “power-domains”, + “device-power-states”, + “device-state-transitions”, + “power-sources”, + “power-management-mapping”, and “controls-power-domains”.
- +
Client Program Requirements - For LoPAR platforms, the client program requirements are defined in + For LoPAR platforms, the client program requirements are defined in , with the following modifications. OF Client Programs for an LoPAR platform shall execute in 32-bit mode with an OF cell size of 1. - +
Load Address - - The client’s load address is specified by the value of the - load-base Configuration Variable. The value of - load-base defines the default load address for - client programs when using the - load method. + + The client’s load address is specified by the value of the + load-base Configuration Variable. The value of + load-base defines the default load address for + client programs when using the + load method. Load-base shall be a real address in real mode or a virtual address in virtual mode. Note that this address represents the area, within the first LMB, into which the client program file will be - read by + read by load; it does not correspond to the addresses at - which the program will be executed. All of physical memory from + which the program will be executed. All of physical memory from load-base to either the start of OF physical memory or the end of physical memory, whichever comes first, shall be available for loading the client program. @@ -9906,28 +9906,28 @@ which the client program will be read by load and does not correspond to the address at which the program will be executed.
- +
Initial Register Values - + The “Initial Register Values” specified in the PA - Binding (see + Binding (see ) are modified as follows: - + r3 -- shall be 0 on client program entry - + r4 -- shall be 0 on client program entry - +
- +
I/O Devices State - + With the exception of the stdin and stdout devices, OF shall close all devices with the following conditions true: All Devices - no DMA and not interrupting @@ -9938,16 +9938,16 @@ RTAS Devices - contract with OF to leave in state to perform intended function
- +
Client Program Format - + The data format of a client program compliant with this specification shall be either ELF (Executable and Linkage Format) as - defined by - , and extended by + defined by + , and extended by , or PE (Portable Executable) - as defined by + as defined by . The standard ELF format contains explicit indication as to the program's execution modes (e.g., 32- or 64-bit, Big- or Little-Endian). LoPAR only supports the 32-bit @@ -9972,7 +9972,7 @@
ELF Note Section - + Part of the process of loading a client program involves verifying its environmental requirements (e.g., endian-ness and address translation mode) against the current firmware configuration. The client’s @@ -9982,12 +9982,12 @@ translation mode) are defined by means of an ELF Note Section (PT_NOTE), pointed to by the program header. The following describes the format of the Note Section for a client program file. - As defined by + As defined by , an ELF file can be “annotated” by means of Note Sections within the executable file. A Note Section contains a “header” followed by a (possibly NULL) “descriptor”, as follows: - + @@ -10000,13 +10000,13 @@ - + Note: The endian format of the values corresponds to the endian-ness specified by the EI-DATA field of the file. The format of a Note Section header can be described by an OF struct as: - + 1275 PowerPC Note Definition - - The ns.name field of the PowerPC OF Note Section shall be + + The ns.name field of the PowerPC OF Note Section shall be “PowerPC”; the ns.type field n shall be 0x1275. Following the Note Section header is a descriptor (desc); the @@ -10025,7 +10025,7 @@ depends upon the kind of Note Section in which it is contained. For the PowerPC OF note, the format of the Note Section’s descriptor can be described by an OF struct, as follows: - + /L field ns.real-mode /L field ns.real-base @@ -10033,32 +10033,32 @@ /L field ns.virt-base /L field ns.virt-size /L field ns.load-base]]> - If the + If the ns.load-base value is not -1, then that value is - compared against the current value of the + compared against the current value of the load-base configuration variable. If they are equal - no further action is taken. If they are not equal then the + no further action is taken. If they are not equal then the load-base configuration variable is set to the value - of + of ns.load-base and the system is rebooted. Note: DATA field of the file.
- +
1275 IBM,RPA-Client-Config Note Definition - + The ns.name field of the LoPAR Client Program Configuration Note - Section shall be + Section shall be “IBM,RPA-Client-Config”; the ns.type field shall be 0x12759999. The format and requirements associated with this ELF Note Section are designed to allow for expandability of the section definition (by adding fields to the end of the section) while retaining forward and backward compatibility for both the 1275 firmware and Client Program. - When the 1275 firmware code recognizes the + When the 1275 firmware code recognizes the “IBM,RPA-Client-Config” note, it creates - a property named + a property named “ibm,rpa-client-config” within the /chosen node reads into this property and interprets the lesser of the descriptor size or the maximum size of the descriptor @@ -10069,34 +10069,34 @@ firmware/client program work as follows: New Firmware/New Client Program: Client Program Header Note contains old plus new fields. - Firmware reads all the new header and places it in + Firmware reads all the new header and places it in “ibm,rpa-client-config” property. Client Program gets feed back that new fields were interpreted by - reading property in + reading property in /chosen. Old Firmware/Old Client Program: Client Program Header Note contains old fields. - Firmware reads all the old definition header and places it in + Firmware reads all the old definition header and places it in “ibm,rpa-client-config” property. Client Program gets feed back that the expected fields were - interpreted by reading property in + interpreted by reading property in /chosen. New Firmware/Old Client Program: Client Program Header Note contains only old fields. Firmware reads only the descriptor length defined in the note - header, and places it in + header, and places it in “ibm,rpa-client-config” property. Client Program gets feed back on the fields that were interpreted - by reading property in + by reading property in /chosen. Firmware uses default values for any missing fields. Old Firmware/New Client Program: Client Program Header Note contains old plus new fields. Firmware reads only the length that it was defined when it was - built, and places it in + built, and places it in “ibm,rpa-client-config” property. Client Program gets feed back that new fields were interpreted by - reading property in + reading property in /chosen, those missing fields indicate function not implemented by the platform. Following the Note Section header is a descriptor (desc); the @@ -10117,13 +10117,13 @@ \ a power of 2 /L field ns.splpar \= “0/1” (default assumption to be “N”) /L field ns.min-load \The minimum amount of code that must be loaded at - \ load-base. + \ load-base. \ (default value -1) -/L field ns.new-mem-def \Flag to indicate use of +/L field ns.new-mem-def \Flag to indicate use of \ ibm,dynamic-reconfiguration-memory definition. \ (default value 0) /L field ns.ignore-my-client-config \Flag: 1 = do not change boot configuration - \ variables based upon the values in this + \ variables based upon the values in this \ header. \ (default value 0) /L field ns.large-page-ready \Flag to indicate the partition OS is prepared for @@ -10132,7 +10132,7 @@ Note: The size of the /L field is based off of e_ident (EI_CLASS) i.e. is 4 for ELFCLASS32. - The + The ns.lparaffinity field is a binary flag whose valid values are 0 or 1. If the field is not one of these valid values the value is assumed to be 0. If the character value is 1, the client program @@ -10141,14 +10141,14 @@ The ns.min-rmo field specifies the minimum amount of real mode addressable storage (in bytes times 2 - 20) that the client program needs to operate. The + 20) that the client program needs to operate. The ns.min-rmo-percent field specifies the minimum percentage (valid values 0-100) of storage that must be real mode addressable for the client program to operate. The platform shall start the client program with a quantity of real mode accessible storage (starting at location 0) of at least the ceiling of these two values. - The + The ns.max-pft-size field value specifies the largest hardware Page Frame Table (in bytes times 2 @@ -10157,7 +10157,7 @@ than this amount The minimum value is 18, the platform ignores the field if the value is less than 18 and uses the platform defined default value. - The + The ns.splpar field is a binary flag whose valid values are 0 or 1. If the field is not one of these valid values the value is assumed to be 0. If the field’s value is 1, the client program @@ -10165,33 +10165,33 @@ character value is not 1 and the partition is running in shared processor mode, platform firmware reports a platform-specific error code and halts the boot. However, if the client-program does not contain an - IBM,RPA-Client-Config + IBM,RPA-Client-Config note, firmware assumes the OS supports shared - processor logical partition mode. This exception only applies to the + processor logical partition mode. This exception only applies to the ns.slpar field. - The + The ns.min-load field specifies the minimum amount of the - client program load module that must be loaded at + client program load module that must be loaded at load-base. If this value is a -1 then the entire - load module must be loaded starting at + load module must be loaded starting at load-base else the client program load fails. The default value is assumed to be -1. If the value of is greater than the platform can support client program load fails. Given that the platform - can load the minimum amount of the client program load module at + can load the minimum amount of the client program load module at load-base, it loads the amount up to the boundary - specified by - ns.min-load starting at + specified by + ns.min-load starting at load-base, then it loads the rest of the load module into contiguous storage at a location selected by platform firmware (default, if possible, is that the residual is loaded immediately following the first segment resulting in a single segment load). - The + The ns.new-mem-def field is a flag which indicates if the ibm,dynamic-reconfiguration-memory representation of reconfigurable memory may be used. The default value 0x00000000 indicates the new definition may not be used. The value 0x00000001 indicates the new - definition may be used. The value 0x00000001 indicates the original version of the new definition may be used. - The value 0x00000002 indicates the version 2 of the new definition may be used. + definition may be used. The value 0x00000001 indicates the original version of the new definition may be used. + The value 0x00000002 indicates the version 2 of the new definition may be used. All other values are reserved for future use. The ns.large-page-ready field is a flag which indicates @@ -10205,15 +10205,15 @@ this mismatch between the partition configuration and the OS capabilities, removes all large pages from the device tree, and continues the OS boot. - If the value of the + If the value of the ns.ignore-my-client-config variable is 0x00000001, - platform firmware must not examine the value of + platform firmware must not examine the value of ns.large-page-ready until the client program calls the PROCESS-ELF-HEADER method. The decision to continue boot should then - be made based on the value of the + be made based on the value of the ns.large-page-ready flag in the updated ELF head passed by this method. - The + The ns.force_alpha_mode field is a flag which indicates that a non-HMC managed I/O services partition with partition management support (VMC) configuration is being requested. The default value of @@ -10229,15 +10229,15 @@ compatible with the partition configuration, the boot process will continue. This flag will be ignored when the system is HMC managed. - +
- +
- +
Recognizing ELF-Format Programs - - The + + The init-program shall recognize client program images that conform to all the requirements listed below as “ELF-format” programs. @@ -10246,54 +10246,54 @@ load-base, and offsets are relative to the beginning of that structure. Multi-byte numerical fields are interpreted according to the endianess specified by the “data” field at offset 5. - - + + The “e_ident” field (at offset 0) contains the string “\7fELF”, where '\7f'’ is a byte whose value is (hex) 7f. This indicates the beginning of an ELF file header. - + The “EI_CLASS” field (at offset 4) contains the value 1. This indicates the 32-bit variant of the ELF format. - + The “e-type” field (at offset 16) contains the value 2. This indicates that the ELF image is executable. - + The “e_machine” field (at offset 18) contains the value 20. This indicates that the ELF image is for the PA instruction set. - + The “e_version” field (at offset 20) contains the value 1. - + The “e_flags” field (at offset 36) contains the value 0. - - + +
- +
Preparing ELF-Format Programs for Execution - + Upon recognition of the client program image at load-base as an ELF-format program, init-program shall prepare the program for execution by performing the following sequence of steps. In the description below, the fields mentioned by name are within ELF “program header” structures, unless specified otherwise. - - + + Search for an ELF “note” section of type “1275” as defined in the section “ELF Note @@ -10301,18 +10301,18 @@ descriptor do not match the firmware's current operating mode, set the appropriate configuration variables to the values specified in the note section descriptor, and restart the firmware so that it will re-execute - the - boot command that resulted in the execution of + the + boot command that resulted in the execution of init-program. - + Set the p_paddr field for each PT_LOAD segment equal to its - p_vaddr field value if + p_vaddr field value if real-mode? is false and p_paddr is -1. This effectively maps these segments v=r. - + Allocate and map, if required, sufficient physical memory for all program segments of type PT_LOAD (i.e. whose “p_type” @@ -10323,60 +10323,60 @@ allow large program images to be loaded without the 2x memory required to move the segments. - + Copy the program headers to a “safe” location to guard against the possibility of them being overwritten by the following steps. - + For each program segment of type “PT_LOAD”: - - + + Copy, if required, the initialized portion of the program segment from its current location in the loaded image to the location given by the section's “p_paddr” field. - + Fill the rest of the segment with zero bytes (i.e., fill “p_memsz - p_filez” bytes beginning at the address “p_paddr + p_filesz”). - + If real-mode? is false, then map the program segment to the virtual address specified by p_vaddr. - + - + - Set the saved program state so that subsequent execution of + Set the saved program state so that subsequent execution of “go” will begin execution at the address given by the “e_entry” field in the ELF file header. The - e_entry field is a physical address if - real-mode? is - TRUE and is a virtual address if + e_entry field is a physical address if + real-mode? is + TRUE and is a virtual address if real-mode? is false. - + The implementation need not take precautions to ensure that the process of copying and zeroing program segments does not overwrite the portions of the load image that have not yet been copied. In order to - guarantee correct copying, the value of the + guarantee correct copying, the value of the load-base configuration variable and the destination addresses of the various sections must be such that such overwriting does not occur. One sufficient condition is that the region of memory - beginning at + beginning at load-base, of size equal to the size of the loaded image, be disjoint from the regions of memory to which the program segments are copied and zero-filled. Another sufficient condition is to - specify a + specify a load-base in the Notes Section (PT_NOTE) that ensures that the PT_LOAD segments are loaded at the address required by their program headers and thus are not moved. There are other less-stringent @@ -10394,24 +10394,24 @@
- +
Additional Client Interface Requirements - + This section describes processor assist callbacks for real and virtual memory management and a service.
Client Interface Callbacks - + This section describes callbacks for memory management. These callbacks are provided by the client.
Real-Mode Memory Management Assist Callbacks - + claim_mem @@ -10428,7 +10428,7 @@ physical memory block which was allocated for OF. - + release_mem @@ -10440,12 +10440,12 @@ - +
- +
Virtual Address Translation Assist Callbacks - + alloc_virt_mem @@ -10459,7 +10459,7 @@ (virt_addr) of the memory block which was allocated. - + free_virt_mem @@ -10470,7 +10470,7 @@ alloc_virt_mem. - + claim_virt @@ -10485,7 +10485,7 @@ allocated. - + release_virt @@ -10505,7 +10505,7 @@
Client Interface Services - OF shall provide the following + OF shall provide the following Client Interface Service: @@ -10534,7 +10534,7 @@ This does not affect how the device tree is presented, which will still assume that a cell is 32 bit in the property values. The method returns using the cell size in which it was called. This method exists only on - platforms that present the + platforms that present the “ibm,enable-ci64-capable” property in the root node. @@ -10548,21 +10548,21 @@
Support Packages - + This section describes the LoPAR Binding specific requirements of OF - support packages. These support packages are - disk-label and - tape-label. For “network” and/or - obp-tftp extensions, refer to + support packages. These support packages are + disk-label and + tape-label. For “network” and/or + obp-tftp extensions, refer to . These packages support the loading and executing of a client program. Another means of executing a Client Program is provided when an OS ROM is a “bootable - device” (Refer to + device” (Refer to , as an example). - +
“disk-label” Support Package - + The process of loading and executing a client program is described in two stages. The first stage determines what partition and/or file (if one exists) to read into memory. This is done by locating a partition and @@ -10574,104 +10574,104 @@ has been determined, the loading is completed in a manner determined by that format. The name of the partition (and, a file contained within the - partition) can be explicitly specified by the user via the - load or + partition) can be explicitly specified by the user via the + load or boot command, or can be implicitly specified by the - value of the + value of the “boot-device” property of the /options node. The partition and filename are the ARGUMENTS portion of the final COMPONENT of the PATH_NAME, as described - in section 4.3.1 of + in section 4.3.1 of . The syntax for explicit partition/filename specification is given - in section + in section below where partition identifies the partition to be used and filename is the name of a file within that partition. If partition is omitted, the default partition (as determined by the partition format) is used. If filename is omitted, the - default filename (i.e., the filename component of the + default filename (i.e., the filename component of the boot-device path-name) is used. - +
Media Layout Format This section describes the media layout formats of Client Program Images that the disk-label support package for an LoPAR platform shall - support; an implementation + support; an implementation may support additional mechanisms, in an - implementation-specific manner. The + implementation-specific manner. The disk-label package for a platform shall support at least four(4) media layout types: - - + + FAT (FAT12 and FAT16 File System) - + FDISK (Partitions 4, 5, 6, 0x41 and 0x96) - + ISO-9660 (9660 File System) - + UDF - - + + An LoPAR platform may choose to support the following media layout formats for historic reasons: - - + + Mac OS (MAC Binary Image) - - + +
FDISK Partition Types - + The following FDISK partition types shall be supported: - - + + Partition Type 4: FAT 12 or FAT 16 File System - + Partition Type 5: Extended Chained Partitions - + Partition Type 6: Extended Partitions - + Partition Type 0x41: Single program image - + Partition Type 0x96: ISO 9660 File System - + Partition Type 0x??: UDF File System - - + + FDISK partition type 0 is a free partition. Partition type 0x82 is reserved and should not be used by this architecture.
- +
- +
Open Method Algorithm - - The - open method of the + + The + open method of the disk-label support package shall implement a disk partition recognition algorithm that supports at least the set of disk formats that are supported by the following algorithm. The following @@ -10679,9 +10679,9 @@ partitions of disks beginning with an FDISK partition map, and files on FAT, UDF and ISO-9660 file systems both within FDISK partitions and by themselves on disks without a partition map. - That + That open method shall accept an argument string (as - returned by + returned by “my-args”) with the following syntax (according to the algorithm below), where brackets denote an optional component: @@ -10702,11 +10702,11 @@ Note: For historic reasons, the following algorithm includes support for the optional MAC OS media layout format. - + PARTITION$, FILENAME$ 2 Else @@ -10728,42 +10728,42 @@ 3 SELECT_ACTIVE_PARTITION 3 If SELECT_ACTIVE_PARTITION returned an error indication 4 Return FALSE -2 \ (At this point, D.OFFSET is set to the beginning of the selected - partition and D.SIZE is set to the size of that partition. If the +2 \ (At this point, D.OFFSET is set to the beginning of the selected + partition and D.SIZE is set to the size of that partition. If the entire disk was selected, D.OFFSET is 0 and D.SIZE is the size of the disk.) 2 Call parent’s “seek” method with an argument of 0,0. 2 Return TRUE 1 CHECK_FOR_BPB procedure -2 If the first four(4) bytes are EBCDIC 'IBMA'(hex character string +2 If the first four(4) bytes are EBCDIC 'IBMA'(hex character string C9C2D4C1), then the sector does not contain a BPB. -2 If the 16-bit little-endian quantity beginning at buffer offset 510 - is 0xAA55, and the 16-bit little-endian quantity beginning at buffer - offset 11 (which is the BPB “bytes per sector” field) is either 256, - 512, or 1024, and the byte at offset 16 (the BPB “number of FATs” field - is either 1 or 2, the sector is deemed to contain a BPB. Otherwise, the +2 If the 16-bit little-endian quantity beginning at buffer offset 510 + is 0xAA55, and the 16-bit little-endian quantity beginning at buffer + offset 11 (which is the BPB “bytes per sector” field) is either 256, + 512, or 1024, and the byte at offset 16 (the BPB “number of FATs” field + is either 1 or 2, the sector is deemed to contain a BPB. Otherwise, the sector does not contain a BPB. 1 CHECK_FOR_ISO_9660 procedure -2 Read 512-byte sector 64 (the beginning of logical 2048-byte sector 16)into +2 Read 512-byte sector 64 (the beginning of logical 2048-byte sector 16)into a buffer. -2 If the byte at offset 0 contains the binary number “1”, and the 5 bytes - beginning at offset 1 contains the text string “CD001”, the partition - or raw disk is deemed to contain an ISO 9660 file system. Otherwise, +2 If the byte at offset 0 contains the binary number “1”, and the 5 bytes + beginning at offset 1 contains the text string “CD001”, the partition + or raw disk is deemed to contain an ISO 9660 file system. Otherwise, the partition or raw disk is deemed not to contain an ISO 9660 file system. 1 CHECK_FOR_FDISK procedure -2 If the buffer does not contain an FDisk partition map signature of “AA55” - as a 16-bit little-endian number beginning at buffer offset 510, the buffer +2 If the buffer does not contain an FDisk partition map signature of “AA55” + as a 16-bit little-endian number beginning at buffer offset 510, the buffer is deemed not to contain an FDISK partition map. 2 If none of the partition type code field (the bytes at buffer offsets 0x1C2, - 0x1D2, 0x1E2, and 0x1F2) contains a recognizable partition type code (4,5, - 6, 0x41, 0x96, or other types that may be recognized by the implementation), + 0x1D2, 0x1E2, and 0x1F2) contains a recognizable partition type code (4,5, + 6, 0x41, 0x96, or other types that may be recognized by the implementation), the buffer is deemed not to contain an FDISK partition map. 2 Otherwise, the buffer is deemed to contain an FDISK partition map. -2 The implementation may, at its option, apply additional validity tests to +2 The implementation may, at its option, apply additional validity tests to the partition map information. 1 CHECK_FOR_MAC_DISK procedure -2 If the first (i.e., at the lowest offset) two bytes in the buffer contains - the 16-bit big-endian signature 0x4552, then the disk is deemed to be a Mac - partitioned disk. Otherwise, the partition or raw disk is deemed not to be +2 If the first (i.e., at the lowest offset) two bytes in the buffer contains + the 16-bit big-endian signature 0x4552, then the disk is deemed to be a Mac + partitioned disk. Otherwise, the partition or raw disk is deemed not to be a Mac partitioned disk.]]> @@ -10790,32 +10790,32 @@ 4 Return OKAY 2 CHECK_FOR_FDISK 2 If the buffer contains an FDISK partition map -3 Search the FDisk partition map, reading new 512-byte sectors into the - buffer if necessary to “chain” to extended partition entries (i.e. ones +3 Search the FDisk partition map, reading new 512-byte sectors into the + buffer if necessary to “chain” to extended partition entries (i.e. ones whose type byte at offset 4 contains “5”) for the first (i.e., at the lowest offset) partition entry whose “bootable” field (at offset 0 in the partition entry) contains 0x80. 3 If a “bootable” partition was found: 4 Set PARTITION-TYPE to that entry's “type” field (the byte at offset 4) -4 Set D.OFFSET to the byte offset from the beginning of the disk of the +4 Set D.OFFSET to the byte offset from the beginning of the disk of the beginning of the partition denoted by that entry. 4 Set D.SIZE to the size of the partition denoted by that entry. 4 INTERPOSE_BY_TYPE 4 Return OKAY \ (If this point is reached, no partition was marked “bootable”) -3 Search the FDisk partition map beginning in 512-byte sector 0,reading new - 512-byte sectors into the buffer if necessary to “chain” to extended - partition entries, for the first partition (i.e., at the lowest offset) - entry whose “type” byte is neither 0 nor 5 (5 is the type code that +3 Search the FDisk partition map beginning in 512-byte sector 0,reading new + 512-byte sectors into the buffer if necessary to “chain” to extended + partition entries, for the first partition (i.e., at the lowest offset) + entry whose “type” byte is neither 0 nor 5 (5 is the type code that indicates a “chained” extended partition entry). 3 If one is found: 4 Set PARTITION-TYPE to that entry's “type” field (the byte at offset 4) -4 Set D.OFFSET to the byte offset from the beginning of the disk of the +4 Set D.OFFSET to the byte offset from the beginning of the disk of the beginning of the partition denoted by that entry. 4 Set D.SIZE to the size of the partition in bytes denoted by that entry. 4 INTERPOSE_BY_TYPE 4 Return OKAY -3 Else \ (If this point is reached, the partition map did not contain any +3 Else \ (If this point is reached, the partition map did not contain any valid partition entries) 4 Return ERROR 2 CHECK_FOR_ISO_9660 @@ -10826,17 +10826,17 @@ 3 Return OKAY 2 CHECK_FOR_MAC_DISK 2 If this is a Mac partitioned disk -3 Search the Mac partition table for the first “bootable” partition. A - partition is “bootable” when the pmPartStatus flags indicate that this is a - valid, allocated, readable and bootable partition and the pmProcessor field +3 Search the Mac partition table for the first “bootable” partition. A + partition is “bootable” when the pmPartStatus flags indicate that this is a + valid, allocated, readable and bootable partition and the pmProcessor field contains “powerpc” (using case-insensitive matching). 3 If a Mac “bootable” partition is found 4 If FILENAME$ is “%BOOT” 5 If the Nth partition is marked bootable -6 Set D.OFFSET to the byte offset from the beginning of the disk +6 Set D.OFFSET to the byte offset from the beginning of the disk to the beginning of the boot area, as given by the pmLgBootStart field. -6 Set D.SIZE to the size of the partition in bytes denoted by +6 Set D.SIZE to the size of the partition in bytes denoted by pmBootSize. 6 Return OKAY 4 Else @@ -10871,14 +10871,14 @@ 4 Return ERROR 2 CHECK_FOR_FDISK 2 If an FDisk partition map is found -3 Search the FDisk partition map beginning in 512-byte sector 0, reading new - 512-byte sectors into the buffer if necessary to “chain” to extended +3 Search the FDisk partition map beginning in 512-byte sector 0, reading new + 512-byte sectors into the buffer if necessary to “chain” to extended partition entries, for the Nth, where N is the value of PARTITION, partition - entry whose “type” byte is neither 0 nor 5 (5 is the type code that + entry whose “type” byte is neither 0 nor 5 (5 is the type code that indicates a “chained” extended partition entry). 3 If the Nth partition is found: 4 Set PARTITION-TYPE to that entry's “type” field (the byte at offset 4) -4 Set D.OFFSET to the byte offset from the beginning of the disk to the +4 Set D.OFFSET to the byte offset from the beginning of the disk to the beginning of the partition denoted by that entry. 4 Set D.SIZE to the size of the partition in bytes denoted by that entry. 4 INTERPOSE_BY_TYPE @@ -10887,15 +10887,15 @@ 4 Return ERROR 2 CHECK_FOR_MAC_DISK 2 If this is a Mac partitioned disk -3 Search the Mac partition map for the Nth partition, where N is the value of +3 Search the Mac partition map for the Nth partition, where N is the value of PARTITION. 3 If the Nth partition is valid, allocated, and readable 4 If FILENAME$ is %BOOT 5 If the Nth partition is marked bootable -6 Set D.OFFSET to the byte offset from the beginning of the disk +6 Set D.OFFSET to the byte offset from the beginning of the disk to the beginning of the boot area, as given by the pmLgBootStart field. -6 Set D.SIZE to the size of the partition in bytes denoted by +6 Set D.SIZE to the size of the partition in bytes denoted by pmBootSize. 6 Return OKAY 5 Else \Nth partition not “bootable” @@ -10909,48 +10909,48 @@ 2 Else \ (If this point is reached, the partition map is not recognized) 3 Return ERROR]]> - + This algorithm can be used to locate the correct partition and/or file and/or load image from the specified device. The boot device is - selected as described in 7.4.3.2 of + selected as described in 7.4.3.2 of . A filename can be explicitly - given as the arguments field of the + given as the arguments field of the device-specifier (i.e., the field following the ':' - of the last path component). Other formats + of the last path component). Other formats may be recognized in an implementation-specific manner. - +
- +
- +
tape-label Support Package - - The + + The tape-label Support Package shall support tape as a standard byte device with the set - of methods specified in + of methods specified in , Section 3.7.3. Presence of the bootinfo.txt file is optional. - The + The open method shall accept an argument string, where brackets denote an optional component: [file number] where the first file on the tape media is located at file number 0. - +
Tape Format - + The LoPAR tape format shall consist of files ending with a file mark (FM). The first block of data will be identified as file 0. The bootinfo.txt file, if present, shall be located on the tape as file 0 (the first file). There shall be only one bootinfo.txt file on the tape - media. Refer to + media. Refer to for the LoPAR Tape format. - +
Tape Boot Format @@ -10968,10 +10968,10 @@
- Tape bootinfo.txt File + Tape bootinfo.txt File The bootinfo.txt file shall have included for each set of <chrp-boot> tags a set of <boot-script> tags that contains - a pointer to the program image to be loaded (Refer to + a pointer to the program image to be loaded (Refer to ). The form for this tape pointer will be: device specifier = device:file number @@ -10983,36 +10983,36 @@ file 0 will be loaded as a bootable image. No other files will be searched if a bootinfo.txt file is not present unless the file number to load is specified by an argument. - +
- +
- +
network Support Package - - The - network Support Package shall adhere to the + + The + network Support Package shall adhere to the documentation functions and conventions. - +
- +
Program-image formats. - + OF must recognize a client program that is formatted as ELF, as - defined in - , and PE, as defined in - . Other formats - may be handled in an implementation-specific manner. + defined in + , and PE, as defined in + . Other formats + may be handled in an implementation-specific manner. defines the FCode and Forth Program-Image Formats. After locating the file, OF reads the image into memory at the location specified by the load-base Configuration Variable. Then, OF must perform the following procedure to prepare the image for execution. - + ”) else FAIL, in an implementation-specific manner.]]> Notes: The following comments apply to the above code: - + - For more information on detecting an ELF format, refer to + For more information on detecting an ELF format, refer to . - For more information on relocating an ELF image, refer to + For more information on relocating an ELF image, refer to . - - + +
- +
- + diff --git a/Platform/ch_system_reqs.xml b/Platform/ch_system_reqs.xml index d38d6cd..6bbda20 100644 --- a/Platform/ch_system_reqs.xml +++ b/Platform/ch_system_reqs.xml @@ -1,30 +1,30 @@ - System Requirements - This chapter gives an operational overview of LoPAR systems and - introduces platform specific software and/or firmware components that are - required for OS support. This chapter also addresses some system level - requirements that are broad in nature and are fundamental to the architecture - described in later chapters. Lastly, a table of requirements is presented as a + This chapter gives an operational overview of LoPAR systems and + introduces platform specific software and/or firmware components that are + required for OS support. This chapter also addresses some system level + requirements that are broad in nature and are fundamental to the architecture + described in later chapters. Lastly, a table of requirements is presented as a guide for platform providers.
System Operation
Control Flow - is an example of typical - phases of operation from power-on to full system operation to termination. This - section gives an overview of the processes involved in moving through these - phases of operation. This section will introduce concepts and terms that will - be explained in more detail in the following chapters. Most requirements + is an example of typical + phases of operation from power-on to full system operation to termination. This + section gives an overview of the processes involved in moving through these + phases of operation. This section will introduce concepts and terms that will + be explained in more detail in the following chapters. Most requirements relating to these processes will also appear in later chapters. - The discussion in this chapter will be restricted to systems with a - single processor. Refer to for the + The discussion in this chapter will be restricted to systems with a + single processor. Refer to for the unique requirements relating to multiprocessor systems.
@@ -37,30 +37,30 @@ xml:lang="en"> -
+
- +
POST - - Power On Self Test (POST) is the process by which the - firmware tests those areas of the hardware that are critical to its ability to - carry out the boot process. It is not intended to be all-inclusive or to be - sophisticated in how it relates to the user. Diagnostics with these + + Power On Self Test (POST) is the process by which the + firmware tests those areas of the hardware that are critical to its ability to + carry out the boot process. It is not intended to be all-inclusive or to be + sophisticated in how it relates to the user. Diagnostics with these characteristics will generally be provided as a service aid. - Platform Implementation Note: The platform - may choose to utilize a service processor to assist in the implementation of - functions during various phases of operation. The service (or support) - processor is not a requirement of this architecture, but is usually seen in the + Platform Implementation Note: The platform + may choose to utilize a service processor to assist in the implementation of + functions during various phases of operation. The service (or support) + processor is not a requirement of this architecture, but is usually seen in the larger systems.
Boot Phase - The following sections describe the boot phase of operation. The + The following sections describe the boot phase of operation. The fundamental parts of the boot phase are: - + Identify and configure system components. @@ -80,38 +80,38 @@ xml:lang="en"> Load the boot image into memory. - +
Identify and Configure System Components - Firmware is generally written with a hardware in mind, so some - components and their configuration data can be hardcoded. Examples of these - components are: type of processor, cache characteristics, and the use of - imbedded components on the planar. This hardcoding is not a requirement, only a + Firmware is generally written with a hardware in mind, so some + components and their configuration data can be hardcoded. Examples of these + components are: type of processor, cache characteristics, and the use of + imbedded components on the planar. This hardcoding is not a requirement, only a practical approach to a part of this task. - R1-R1--1. - The firmware must, by various means, - become aware of all components in the system associated with the boot process - and configure or reset those components into a known state (components include, + The firmware must, by various means, + become aware of all components in the system associated with the boot process + and configure or reset those components into a known state (components include, for example, buses, bridges, I/O Adapters (IOAs) - See for - the definition of an IOA., + See for + the definition of an IOA., and I/O devices). - + - R1-R1--2. - The firmware must obtain certain system - information which is necessary to build the OF device tree from - “walking” the I/O buses (for example, identification of IOAs and + The firmware must obtain certain system + information which is necessary to build the OF device tree from + “walking” the I/O buses (for example, identification of IOAs and bridges). @@ -123,23 +123,23 @@ xml:lang="en"> - R1-R1--1. - The firmware must build a device tree - and the OS must gain access to the device tree through Client Interface + The firmware must build a device tree + and the OS must gain access to the device tree through Client Interface Services (CIS). - + - R1-R1--2. - Configuration information - (configuration variables) which are stored in non-volatile memory must be - stored under the partition names of-config or - common, depending on the nature of the information (see + Configuration information + (configuration variables) which are stored in non-volatile memory must be + stored under the partition names of-config or + common, depending on the nature of the information (see ). @@ -148,40 +148,40 @@ xml:lang="en">
Initialize/Reset System Components - The OS requires devices to be in a known state at the time control - is transferred from the firmware. Firmware may gain control with the hardware + The OS requires devices to be in a known state at the time control + is transferred from the firmware. Firmware may gain control with the hardware in various states depending on what has initiated the boot process. - + - Normal boot: Initiated by a power-on sequence; all devices and + Normal boot: Initiated by a power-on sequence; all devices and registers begin in a hardware reset state. - + - Reboot: Device state is unpredictable at the start of a + Reboot: Device state is unpredictable at the start of a reboot. - - - The hardware reset state for a device is an inactive state. An - inactive state is defined as a state that allows no system level activity; - there can be no bus activity, interrupt requests, or DMA requests possible from - the IOA that is in a reset state. Since the OS may configure devices in a - manner that requires very specific control over these functions to avoid - transitory resource conflicts, these functions should be disabled at the device - and not at a central controlling agent (for example, the interrupt controller). - Devices that do not share any resources may have these resources disabled at a - system level (for example, keyboard interrupts may be disabled at the interrupt + + + The hardware reset state for a device is an inactive state. An + inactive state is defined as a state that allows no system level activity; + there can be no bus activity, interrupt requests, or DMA requests possible from + the IOA that is in a reset state. Since the OS may configure devices in a + manner that requires very specific control over these functions to avoid + transitory resource conflicts, these functions should be disabled at the device + and not at a central controlling agent (for example, the interrupt controller). + Devices that do not share any resources may have these resources disabled at a + system level (for example, keyboard interrupts may be disabled at the interrupt controller in standard configurations). - R1-R1--1. - IOAs must adhere to the reset states - given in when control of the system + IOAs must adhere to the reset states + given in when control of the system is passed from firmware to an OS. @@ -256,104 +256,104 @@ xml:lang="en">
- + - R1-R1--2. - The platform must include the root node - OF device tree property “ibm,pci-full-cfg” with a - value of 1 and configure the configuration registers of all PCI IOAs and + The platform must include the root node + OF device tree property “ibm,pci-full-cfg” with a + value of 1 and configure the configuration registers of all PCI IOAs and bridges as specified by Requirement . - + - R1-R1--3. - Prior to passing control to the OS, the platform must initialize all processor registers to a value which, if + Prior to passing control to the OS, the platform must initialize all processor registers to a value which, if accessed, will not yield a machine check. - + - R1-R1--4. - Prior to passing control to the OS, the - platform must initialize all registers not visible to the OS to a state that is + Prior to passing control to the OS, the + platform must initialize all registers not visible to the OS to a state that is consistent with the system view represented by the OF device tree. - + - R1-R1--5. - During boot or reboot operations and - prior to passing control to the OS, the platform must initialize the interrupt + During boot or reboot operations and + prior to passing control to the OS, the platform must initialize the interrupt controller. - + - R1-R1--6. - Hardware must provide a mechanism, - callable by software, to hard reset all processors and I/O subsystems in order + Hardware must provide a mechanism, + callable by software, to hard reset all processors and I/O subsystems in order to facilitate the implementation of the RTAS system-reboot function. - Platform Implementation Note: The platform - is required to reset the interrupt controller to avoid inconsistency among the - states of IOAs, the interrupt controller, and software interrupt handler + Platform Implementation Note: The platform + is required to reset the interrupt controller to avoid inconsistency among the + states of IOAs, the interrupt controller, and software interrupt handler routines. The reset state is shown in . - Software and Firmware Implementation Note: - The conventional PCI configuration registers are further described in the - and are copied into OF properties described - in the . PCI-X configuration registers - are further described in the . PCI - Express configuration registers are further described in the - . PCI-X IOAs and bridges and PCI Express - IOAs, bridges, and switches are treated the same as conventional PCI IOAs and + Software and Firmware Implementation Note: + The conventional PCI configuration registers are further described in the + and are copied into OF properties described + in the . PCI-X configuration registers + are further described in the . PCI + Express configuration registers are further described in the + . PCI-X IOAs and bridges and PCI Express + IOAs, bridges, and switches are treated the same as conventional PCI IOAs and bridges for purposes of generation of OF properties. - Software and Firmware Implementation Note: In - reference to Requirement , generally - the initial value of processor registers is contained in the processor binding. - However, some processors have deviations on register usage. Also, since some + Software and Firmware Implementation Note: In + reference to Requirement , generally + the initial value of processor registers is contained in the processor binding. + However, some processors have deviations on register usage. Also, since some register implementation is optional, all processors are not the same.
Locate an OS Boot Image - The OS boot image is located as described in - . A device and filename can be specified directly - from the command interpreter (the boot command) or OF - will locate the image through an automatic boot process controlled by - configuration variables. Once a boot image is located, the device path is set - in the device tree as the “bootpath” + The OS boot image is located as described in + . A device and filename can be specified directly + from the command interpreter (the boot command) or OF + will locate the image through an automatic boot process controlled by + configuration variables. Once a boot image is located, the device path is set + in the device tree as the “bootpath” property of the chosen node. - The devices searched by the automatic boot process are those - contained in the boot-device configuration variable. - Implementations may choose to limit the number of boot device entries that are - searched. The root node device tree property - “ibm,max-boot-devices” communicates the number of + The devices searched by the automatic boot process are those + contained in the boot-device configuration variable. + Implementations may choose to limit the number of boot device entries that are + searched. The root node device tree property + “ibm,max-boot-devices” communicates the number of boot-device entries that the platform processes. - If multi-boot (multiple bootable OSs residing on the same platform) is supported, - a configuration variable instructs the firmware to display a multi-boot menu - from which the OS and bootpath are selected. See + If multi-boot (multiple bootable OSs residing on the same platform) is supported, + a configuration variable instructs the firmware to display a multi-boot menu + from which the OS and bootpath are selected. See for information relating to the multiboot process. - R1-R1--1. - The platform must supply in the OF root + The platform must supply in the OF root node the “ibm,max-boot-devices” property. @@ -362,18 +362,18 @@ xml:lang="en">
Load the Boot Image into Memory - After locating the image, it is loaded into memory at the location + After locating the image, it is loaded into memory at the location given by a configuration variable or as specified by the OS load image format.
- +
Boot Process - The boot process is described in . - Steps in the process are reviewed here, but the - authoritative and complete description of the process is included in - . is a - depiction of the boot flow showing the action of the f1, f5, and f6 function - keys. The figure should only be used as an aid in understanding the + The boot process is described in . + Steps in the process are reviewed here, but the + authoritative and complete description of the process is included in + . is a + depiction of the boot flow showing the action of the f1, f5, and f6 function + keys. The figure should only be used as an aid in understanding the requirements for LoPAR systems.  
@@ -393,33 +393,33 @@ xml:lang="en"> - R1-R1--1. - After the banner step of the boot sequence, the platform display must present - a clearly visible graphical or text message (boot prompt), and - must provide a reaction window of at least 3 seconds that prompts the - user to activate various options including the f1, f5, and f6 control keys + After the banner step of the boot sequence, the platform display must present + a clearly visible graphical or text message (boot prompt), and + must provide a reaction window of at least 3 seconds that prompts the + user to activate various options including the f1, f5, and f6 control keys detailed in this document. - + - R1-R1--2. - The functions provided by f1, f5 and - f6 described in this chapter must be equivalently provided by the tty numeral + The functions provided by f1, f5 and + f6 described in this chapter must be equivalently provided by the tty numeral keys 1, 5, and 6, respectively when a serial terminal is attached. - + - R1-R1--3. - The boot prompt must identify the - platform and communicate to the user that there are options that may be invoked + The boot prompt must identify the + platform and communicate to the user that there are options that may be invoked to alter the boot process. @@ -428,140 +428,140 @@ xml:lang="en">
The Menus - Once the boot prompt is displayed, the System Management Services - (SMS) menu can be invoked. SMS provides a user interface for utilities, - configuration, and the Multiboot Menu (as introduced in - ) for boot/install and the OF command + Once the boot prompt is displayed, the System Management Services + (SMS) menu can be invoked. SMS provides a user interface for utilities, + configuration, and the Multiboot Menu (as introduced in + ) for boot/install and the OF command interpreter. - The Multiboot menu is formatted so that block devices that - currently contain boot information are most easily selected by the user. - Because of the serial nature of byte devices, they should not be opened unless - specifically included in a boot list. The user may also wish to add devices to - the boot-device and/or diag-device configuration variables (boot lists) that - currently do not contain boot information. The Multiboot menu presents these + The Multiboot menu is formatted so that block devices that + currently contain boot information are most easily selected by the user. + Because of the serial nature of byte devices, they should not be opened unless + specifically included in a boot list. The user may also wish to add devices to + the boot-device and/or diag-device configuration variables (boot lists) that + currently do not contain boot information. The Multiboot menu presents these devices in a secondary manner. - If the Multiboot Menu boot/install option is chosen, OF will - execute the bootinfo.txt<boot-script> of the - selected OS, and if the user elects to make this the default, the - boot-command variable will be set equal to the contents of + If the Multiboot Menu boot/install option is chosen, OF will + execute the bootinfo.txt<boot-script> of the + selected OS, and if the user elects to make this the default, the + boot-command variable will be set equal to the contents of bootinfo.txt<boot-script>. - R1-R1--1. - The SMS menu must provide a means to + The SMS menu must provide a means to display the Multiboot Menu. - + - R1-R1--2. - If, after the boot - prompt is displayed, - auto-boot? = false - and menu? = true, + If, after the boot + prompt is displayed, + auto-boot? = false + and menu? = true, the firmware must display the Multiboot Menu directly. - + - R1-R1--3. - The Multiboot Menu must present all - potential boot device options, differentiating block devices that contain + The Multiboot Menu must present all + potential boot device options, differentiating block devices that contain locatable bootinfo objects. - + - R1-R1--4. - Firmware must evaluate all - bootinfo objects at each invocation of the Multiboot Menu to ensure + Firmware must evaluate all + bootinfo objects at each invocation of the Multiboot Menu to ensure that any modifications made by the OS will be included. - + - R1-R1--5. - The Multiboot Menu must provide a - means to enter the currently selected boot option into the desired location - within the boot-device/boot-file or + The Multiboot Menu must provide a + means to enter the currently selected boot option into the desired location + within the boot-device/boot-file or diag-device/diag-file configuration variables. - + - R1-R1--6. - The platform must provide a means to - delete individual boot options from the - boot-device/boot-file and + The platform must provide a means to + delete individual boot options from the + boot-device/boot-file and diag-device/diag-file configuration variables. - + - R1-R1--7. - The Multiboot Menu must provide an - option for the user to select whether or not to return to the Multiboot Menu on + The Multiboot Menu must provide an + option for the user to select whether or not to return to the Multiboot Menu on each boot. - Firmware Implementation Note: Returning to the Multiboot Menu on - reboot is controlled with the auto-boot? and + Firmware Implementation Note: Returning to the Multiboot Menu on + reboot is controlled with the auto-boot? and menu? configuration variables.
The f1 Key - The boot process is further controlled by the - auto-boot? and - menu? + The boot process is further controlled by the + auto-boot? and + menu? OF configuration variables and the f1 key. - R1-R1--1. - If, after the boot - prompt is displayed, function key f1 is pushed or if - auto-boot? = false and - menu? = false, the firmware must display the + If, after the boot + prompt is displayed, function key f1 is pushed or if + auto-boot? = false and + menu? = false, the firmware must display the System Management Services (SMS) menu. - + - R1-R1--2. - The default value for the - auto-boot? configuration variable must be + The default value for the + auto-boot? configuration variable must be true. - + - R1-R1--3. The default value for the - menu? configuration variable must be + menu? configuration variable must be false. @@ -570,157 +570,157 @@ xml:lang="en">
The f5 and f6 Keys - If auto-boot? = true, - the commands specified by the boot-command configuration + If auto-boot? = true, + the commands specified by the boot-command configuration variable are executed. - If the boot command has no arguments, IEEE + If the boot command has no arguments, IEEE 1275 states that the arguments are determined as follows: - + - Normal Boot - If the - diagnostic-mode?FCode - function returns false, the boot - device is given by boot-device and the default boot + Normal Boot - If the + diagnostic-mode?FCode + function returns false, the boot + device is given by boot-device and the default boot arguments are given by boot-file. - + - Diagnostics Boot - If the diagnostic-mode? - FCode function returns true, the boot device is given by - diag-device and the default boot arguments are given by + Diagnostics Boot - If the diagnostic-mode? + FCode function returns true, the boot device is given by + diag-device and the default boot arguments are given by diag-file. - + Platform Implementation Note: - boot-device, - boot-file, - diag-device and - diag-file - are potentially multi-entry strings. The - boot-command searches the - devices specified in boot-device/diag-device in the order - defined by the string for the boot-file/diag-file to load - into system memory. Failure occurs only if no corresponding file is + boot-device, + boot-file, + diag-device and + diag-file + are potentially multi-entry strings. The + boot-command searches the + devices specified in boot-device/diag-device in the order + defined by the string for the boot-file/diag-file to load + into system memory. Failure occurs only if no corresponding file is found/usable on any of the specified devices. - Platforms give the user the ability to control the boot process - further with function keys f5 and f6 (within the window described in + Platforms give the user the ability to control the boot process + further with function keys f5 and f6 (within the window described in Requirement ). - R1-R1--1. - If, after the boot prompt is displayed, function key f5 is pushed (and - auto-boot? = true), then - diagnostic-mode? must return true and the - default diagnostic device as defined in Requirements - and - must be used to locate bootable + If, after the boot prompt is displayed, function key f5 is pushed (and + auto-boot? = true), then + diagnostic-mode? must return true and the + default diagnostic device as defined in Requirements + and + must be used to locate bootable media. - + - R1-R1--2. - If, after the boot prompt is displayed, function key f6 is pushed (and - auto-boot? = true), then - diagnostic-mode? must return true and - diag-device must be used to locate the boot image, else - if diag-device is empty, then its default as defined in - Requirements and - must be used to locate bootable + If, after the boot prompt is displayed, function key f6 is pushed (and + auto-boot? = true), then + diagnostic-mode? must return true and + diag-device must be used to locate the boot image, else + if diag-device is empty, then its default as defined in + Requirements and + must be used to locate bootable media. - + - R1-R1--3. - boot-command - must default to boot <with no + boot-command + must default to boot <with no arguments>. - + - R1-R1--4. - boot-device and - diag-device - must default to the first devices of each type that + boot-device and + diag-device + must default to the first devices of each type that would be encountered by a search of the device tree. - + - R1-R1--5. - The search order for the - boot-device and - diag-device + The search order for the + boot-device and + diag-device defaults must be floppy, cdrom, tape, disk, network. - + - R1-R1--6. - boot-file must + boot-file must default to <null>. - + - R1-R1--7. - diag-file must + diag-file must default to diag. - Note: Requirement - provides a method to invoke stand-alone - diagnostics or to start reinstallation without going through the menus. - Requirement provides a method to boot + Note: Requirement + provides a method to invoke stand-alone + diagnostics or to start reinstallation without going through the menus. + Requirement provides a method to boot with on-line diagnostics. - Software Implementation Note: Pressing either f5 or f6 at the - correct time will cause the contents of diag-file to be - set into the “bootargs” property of the - chosen node of the device tree. The OS can recognize a - diagnostics boot request when it finds the “diag” + Software Implementation Note: Pressing either f5 or f6 at the + correct time will cause the contents of diag-file to be + set into the “bootargs” property of the + chosen node of the device tree. The OS can recognize a + diagnostics boot request when it finds the “diag” substring in “bootargs”.
CDROM Boot - If the CDROM is the first bootable media found in the devices - listed in the bootlist (boot-device strings), the CDROM - should boot without having to enter optional file specification information or - using the f5 function key normally used for diagnostic boot. This is - accomplished by having the appropriate bootinfo.txt file + If the CDROM is the first bootable media found in the devices + listed in the bootlist (boot-device strings), the CDROM + should boot without having to enter optional file specification information or + using the f5 function key normally used for diagnostic boot. This is + accomplished by having the appropriate bootinfo.txt file specification in the CDROM entry in the bootlist. - R1-R1--1. - CDROM entries for the default OF - boot-device and - diag-device - configuration variables must include the standard block device - bootinfo.txt file specification as documented in + CDROM entries for the default OF + boot-device and + diag-device + configuration variables must include the standard block device + bootinfo.txt file specification as documented in (\ppc\bootinfo.txt). @@ -734,20 +734,20 @@ xml:lang="en">
Network Boot - The user selects from a list of network devices on the Multiboot - Menu and then selects the boot option. The user may be prompted for network - parameters (IP addresses, etc.) which are set as arguments in - boot-device by the firmware. If the BOOTP protocol is used, the - BOOTREPLY packet contains the network parameters to be used for subsequent - transmissions (see for details of + The user selects from a list of network devices on the Multiboot + Menu and then selects the boot option. The user may be prompted for network + parameters (IP addresses, etc.) which are set as arguments in + boot-device by the firmware. If the BOOTP protocol is used, the + BOOTREPLY packet contains the network parameters to be used for subsequent + transmissions (see for details of this process). - R1-R1--1. - If network boot is selected, firmware + If network boot is selected, firmware must provide a means for the user to specify or override network parameters. @@ -756,19 +756,19 @@ xml:lang="en">
Service Processor Boot - In platforms with a service processor, the user may call for a boot - using a local/remote connection to the service processor. The particular port - used for this remote session is sent to the firmware in a status message after - the service processor finishes POST. The port is identified in the + In platforms with a service processor, the user may call for a boot + using a local/remote connection to the service processor. The particular port + used for this remote session is sent to the firmware in a status message after + the service processor finishes POST. The port is identified in the “stdin” - and “stdout” + and “stdout” properties in the chosen node of the OF device tree.
Console Selection - During the boot process, firmware establishes the console to be - used for displaying status and menus. The following pseudocode describes the + During the boot process, firmware establishes the console to be + used for displaying status and menus. The following pseudocode describes the console selection process: - R1-R1--1. - If a console has been selected during - the boot process, firmware must set the “stdin” - and “stdout” properties of the - chosen node to the ihandles of this console’s input and + If a console has been selected during + the boot process, firmware must set the “stdin” + and “stdout” properties of the + chosen node to the ihandles of this console’s input and output devices prior to passing control to the OS. @@ -801,29 +801,29 @@ ELSE
Boot Retry - For boot failures related to firmware trying to access a boot - device, it is appropriate for the platform to retry the boot operation, - especially in the case of booting from a network device. However, in platforms - which have a service processor, there are several other types of detected - errors for which a reboot retry may be appropriate; for example, checkstops or - loss of communication between firmware and the service processor. To ensure - that the user policy is followed, the coordination and counting of retry - attempts need to be interlocked between the service processor and boot - firmware. The most straightforward way to implement this is to have the boot - firmware inform the service processor of all failed boot attempts, and let the - service processor initiate the system reset (as it also would for checkstops or - hangs). This way the service processor can easily manage the retry count and + For boot failures related to firmware trying to access a boot + device, it is appropriate for the platform to retry the boot operation, + especially in the case of booting from a network device. However, in platforms + which have a service processor, there are several other types of detected + errors for which a reboot retry may be appropriate; for example, checkstops or + loss of communication between firmware and the service processor. To ensure + that the user policy is followed, the coordination and counting of retry + attempts need to be interlocked between the service processor and boot + firmware. The most straightforward way to implement this is to have the boot + firmware inform the service processor of all failed boot attempts, and let the + service processor initiate the system reset (as it also would for checkstops or + hangs). This way the service processor can easily manage the retry count and initiate a service dial-out if the boot retry limit is exceeded. - R1-R1--1. - Platform - Implementation: In platforms with service processors, retry of - failed boot operations must be coordinated between boot firmware and the - service processor, to ensure correct counting and handling of reboot retries + Platform + Implementation: In platforms with service processors, retry of + failed boot operations must be coordinated between boot firmware and the + service processor, to ensure correct counting and handling of reboot retries according to the service processor configuration reboot policies. @@ -832,88 +832,88 @@ ELSE
Boot Failures - Failure to boot occurs only when no corresponding file is found - which is usable on any device specified in the - boot-device, - boot-file, - diag-device, or + Failure to boot occurs only when no corresponding file is found + which is usable on any device specified in the + boot-device, + boot-file, + diag-device, or diag-file string being used. - R1-R1--1. - If an error occurs in a boot device - preventing boot from that device, and after all defined retries have occurred, + If an error occurs in a boot device + preventing boot from that device, and after all defined retries have occurred, the failure must be reported as a POST error. - + - R1-R1--2. - If a boot device is physically - missing or lacks a boot record (for example, if a CDROM is not present in a - CDROM drive), then a POST error must be generated for this case, must not - result in the calling out of a boot device as being defective, and must not + If a boot device is physically + missing or lacks a boot record (for example, if a CDROM is not present in a + CDROM drive), then a POST error must be generated for this case, must not + result in the calling out of a boot device as being defective, and must not result in a hardware service repair action to the device. - + - R1-R1--3. - In Requirement - , if it is not possible for a device to - distinguish between an actual device error, as opposed to a missing device or - boot record, then a POST error must be generated that indicates the possible - causes of the failure to boot from the device, and this POST error must not - imply that a hardware service repair action is required for the boot + In Requirement + , if it is not possible for a device to + distinguish between an actual device error, as opposed to a missing device or + boot record, then a POST error must be generated that indicates the possible + causes of the failure to boot from the device, and this POST error must not + imply that a hardware service repair action is required for the boot device. - Implementation Note: All device errors of the - same type may be consolidated into a single POST log entry with multiple - location codes listed if needed. This architecture anticipates remote support - center notification of hardware errors. It is the intention that only - definitive boot device errors will be reported as requiring hardware repair. - This is meant to prevent service calls for systems for non-hardware errors such + Implementation Note: All device errors of the + same type may be consolidated into a single POST log entry with multiple + location codes listed if needed. This architecture anticipates remote support + center notification of hardware errors. It is the intention that only + definitive boot device errors will be reported as requiring hardware repair. + This is meant to prevent service calls for systems for non-hardware errors such as no tape in a tape drive.
- Persistent Memory and Memory Preservation Boot + <title>Persistent Memory and Memory Preservation Boot (Storage Preservation Option) - Selected regions of storage, or Logical Memory Blocks (LMBs), may - be optionally preserved across client program boot cycles. These LMBs are - denoted by the presence of the “ibm,preservable” - property in their OF device tree /memory node. - The client program registers the LMB with - the platform using the ibm,manage-storage-preservation - RTAS call if it wants the contents of the storage preserved across client boot - cycles (see also "Managing Storage Preservations" in - specification). The architectural intent of this - facility is to enable client programs to emulate persistent storage. This is - done by a client program registering preservable LMBs. Then, after a subsequent - boot cycle (perhaps due to error or impending power loss) the presence of the - “ibm,preserved-storage” property in the - /rtas node of the device tree indicates to the client - program that it has preserved memory. When the client program detects that it - has booted with preserved storage and that it might be necessary to preserve - the storage for long term, the client program is responsible for copying the - preserved data to long term persistent storage medium, and then clearing the - registration of the preserved LMBs to prevent potential corruption of the + Selected regions of storage, or Logical Memory Blocks (LMBs), may + be optionally preserved across client program boot cycles. These LMBs are + denoted by the presence of the “ibm,preservable” + property in their OF device tree /memory node. + The client program registers the LMB with + the platform using the ibm,manage-storage-preservation + RTAS call if it wants the contents of the storage preserved across client boot + cycles (see also "Managing Storage Preservations" in + specification). The architectural intent of this + facility is to enable client programs to emulate persistent storage. This is + done by a client program registering preservable LMBs. Then, after a subsequent + boot cycle (perhaps due to error or impending power loss) the presence of the + “ibm,preserved-storage” property in the + /rtas node of the device tree indicates to the client + program that it has preserved memory. When the client program detects that it + has booted with preserved storage and that it might be necessary to preserve + the storage for long term, the client program is responsible for copying the + preserved data to long term persistent storage medium, and then clearing the + registration of the preserved LMBs to prevent potential corruption of the persistent storage medium due to subsequent failures. - Upon reboot after such an operation, the - “ibm,request-partition-shutdown” property is provided - in the /rtas node with a value of 2, indicating that the + Upon reboot after such an operation, the + “ibm,request-partition-shutdown” property is provided + in the /rtas node with a value of 2, indicating that the client program should save appropriate data and shutdown the partition. - Implementation Note: How areas get chosen to + Implementation Note: How areas get chosen to be marked as preservable is beyond the scope of this architecture.
@@ -922,99 +922,99 @@ ELSE
Transfer Phase - The image is prepared for execution by checking it against certain + The image is prepared for execution by checking it against certain configuration variables; this may result in a reboot. - Once the OS gains control, it may use the CIS interface to learn - about the platform contents and configuration. The OS will generally build its - own version of this configuration data and may discard the OF code and device - tree in order to reclaim the space used by OF. A set of - platform-specific functions are provided by Run-Time Abstraction Services - (RTAS) which is instantiated by the OS invoking the + Once the OS gains control, it may use the CIS interface to learn + about the platform contents and configuration. The OS will generally build its + own version of this configuration data and may discard the OF code and device + tree in order to reclaim the space used by OF. A set of + platform-specific functions are provided by Run-Time Abstraction Services + (RTAS) which is instantiated by the OS invoking the instantiate-rtas method of the RTAS OF device tree node. - R1-R1--1. - If any device tree property is presented - that contains a phandle value to identify a certain node in the device tree, - the device tree node so identified must contain the - “ibm,phandle” property, and the value of the - “ibm,phandle” property must match the + If any device tree property is presented + that contains a phandle value to identify a certain node in the device tree, + the device tree node so identified must contain the + “ibm,phandle” property, and the value of the + “ibm,phandle” property must match the phandle value in the property identifying that node. - + - R1-R1--2. - If the “ibm,phandle” - property is present in a device tree - node, the OS must use this value, and not the phandle value returned by a - client interface service, to associate this node with a device tree property + If the “ibm,phandle” + property is present in a device tree + node, the OS must use this value, and not the phandle value returned by a + client interface service, to associate this node with a device tree property that uses a phandle value to identify this node. - + - R1-R1--3. - An OS must not assume that the - “ibm,phandle” property, if present, corresponds to the - phandle used by or returned by OF client interface services. A phandle value - passed to a client interface service as an argument must have been obtained by - use of a client interface service, and not from a device tree property + An OS must not assume that the + “ibm,phandle” property, if present, corresponds to the + phandle used by or returned by OF client interface services. A phandle value + passed to a client interface service as an argument must have been obtained by + use of a client interface service, and not from a device tree property value. - Note: If the “ibm,phandle” - property exists, there are two “phandle” namespaces which must be kept separate. One is that - actually used by the OF client interface, the other is properties in the device - tree making reference to device tree nodes. These requirements are written to - maintain backward compatibility with older FW versions predating these - requirements; if the “ibm,phandle” property - is not present, the OS may assume that any device tree properties which refer - to this node will have a phandle value matching that returned by client - interface services. It will be necessary to have the OSs ready for this + Note: If the “ibm,phandle” + property exists, there are two “phandle” namespaces which must be kept separate. One is that + actually used by the OF client interface, the other is properties in the device + tree making reference to device tree nodes. These requirements are written to + maintain backward compatibility with older FW versions predating these + requirements; if the “ibm,phandle” property + is not present, the OS may assume that any device tree properties which refer + to this node will have a phandle value matching that returned by client + interface services. It will be necessary to have the OSs ready for this requirement before the firmware implementation.
Run-Time - During run-time, the OS has control of the system and will have + During run-time, the OS has control of the system and will have RTAS instantiated to provide low-level hardware-specific functions.
Termination - Termination is the phase during which the OS yields control of the - system and may return control to the firmware depending on the nature of the + Termination is the phase during which the OS yields control of the + system and may return control to the firmware depending on the nature of the terminating condition.
Power Off - If the user activates the system power switch, power may be removed - from the hardware immediately (switch directly controls the power supply) or - software may be given an opportunity to bring the system down in an orderly + If the user activates the system power switch, power may be removed + from the hardware immediately (switch directly controls the power supply) or + software may be given an opportunity to bring the system down in an orderly manner (power management control of the power switch). - If power is removed from the hardware immediately, the OS will lose - control of the system in an undetermined state. Any I/O underway will be - involuntarily aborted and there is potential for data loss or system damage. A + If power is removed from the hardware immediately, the OS will lose + control of the system in an undetermined state. Any I/O underway will be + involuntarily aborted and there is potential for data loss or system damage. A shut-down process prior to power removal is highly recommended. - In most power managed systems, power switch activation is fielded - as a power management interrupt and the OS (through RTAS) is able to quiesce - the system before removing power. The OS may turn off system power using the + In most power managed systems, power switch activation is fielded + as a power management interrupt and the OS (through RTAS) is able to quiesce + the system before removing power. The OS may turn off system power using the RTAS power-off function.
Reboot - The OS may cause the system to reset and reboot by calling the RTAS + The OS may cause the system to reset and reboot by calling the RTAS system-reboot function.
@@ -1026,42 +1026,42 @@ ELSE - R1-R1--1. Platforms must implement OF as defined in . - + - R1-R1--2. - The OF User Interface must include the - following methods as specified in , - Section 7.6:.registers, - to, - load, - go, - state-valid + The OF User Interface must include the + following methods as specified in , + Section 7.6:.registers, + to, + load, + go, + state-valid and init-program. - + - R1-R1--3. - Platforms must implement the Run-Time Abstraction Services (RTAS) as described in + Platforms must implement the Run-Time Abstraction Services (RTAS) as described in . - + - R1-R1--4. - OSs must use OF and the RTAS functions to be + OSs must use OF and the RTAS functions to be compatible with all platforms. @@ -1070,29 +1070,29 @@ ELSE
OS Installation - Installation of OSs will be accomplished through the Multiboot Menu + Installation of OSs will be accomplished through the Multiboot Menu as follows: - + - The system boots or reboots normally; the user enters the + The system boots or reboots normally; the user enters the Multiboot Menu by one of the methods described herein. - The Multiboot Menu presents a list of all installation + The Multiboot Menu presents a list of all installation devices. - The user selects “install” and an installation - device from the menu; firmware locates the bootinfo object or install image on + The user selects “install” and an installation + device from the menu; firmware locates the bootinfo object or install image on the selected installation device. - Firmware will execute init-program and, if a - bootinfo object was found, firmware parses it, replaces the <boot-script> + Firmware will execute init-program and, if a + bootinfo object was found, firmware parses it, replaces the <boot-script> entities with appropriate values and executes the script. @@ -1101,34 +1101,34 @@ ELSE - After the install process is determined to be successful, the OS - updates variables such as boot-device, - boot-file, + After the install process is determined to be successful, the OS + updates variables such as boot-device, + boot-file, and boot-command. - The OS adds the bootinfo-nnnn configuration + The OS adds the bootinfo-nnnn configuration variable to the NVRAM common system partition. - + - R1-R1--1. - The Multiboot Menu must provide an option for + The Multiboot Menu must provide an option for OS installation that lists all possible installation devices. - + - R1-R1--2. - After the install process is determined to be successful, the OS - must set boot-device, + After the install process is determined to be successful, the OS + must set boot-device, boot-file, and boot-command. @@ -1137,22 +1137,22 @@ ELSE
Tape Install - The OF definition of installation from tape is defined in + The OF definition of installation from tape is defined in .
Network Install - Network install follows the same process as network boot with the - exception that after installation is complete, the OS will write + Network install follows the same process as network boot with the + exception that after installation is complete, the OS will write boot-device with the target device information. - R1-R1--1. - If network install is selected, firmware + If network install is selected, firmware must provide a means for the user to override default network parameters. @@ -1162,45 +1162,45 @@ ELSE
Diagnostics - IBM Power® system platforms may use IBM AIX® Kernel-based - stand-alone diagnostics as their multi-OS common diagnostics package. Since AIX - will run on other vendors’ platforms which might not have permission to - use AIX diagnostics, the “ibm,aix-diagnostics” - property indicates that AIX diagnostics are permitted (see "Root + IBM Power® system platforms may use IBM AIX® Kernel-based + stand-alone diagnostics as their multi-OS common diagnostics package. Since AIX + will run on other vendors’ platforms which might not have permission to + use AIX diagnostics, the “ibm,aix-diagnostics” + property indicates that AIX diagnostics are permitted (see "Root Node Properties" in ). - R1-R1--1. - If AIX diagnostics are supported on a - platform, then the firmware for that platform must include the property - “ibm,aix-diagnostics” in the + If AIX diagnostics are supported on a + platform, then the firmware for that platform must include the property + “ibm,aix-diagnostics” in the root node. - Software Implementation Note: Each OS may implement an OS-specific - run-time diagnostics package, but should, for purposes of consistency, adhere + Software Implementation Note: Each OS may implement an OS-specific + run-time diagnostics package, but should, for purposes of consistency, adhere to the error log formats in .
Platform Class - The “ibm,model-class” OF property - is defined to classify platforms for planning, marketing, licensing, and - service purposes (see "Root Node Properties" in + The “ibm,model-class” OF property + is defined to classify platforms for planning, marketing, licensing, and + service purposes (see "Root Node Properties" in ). - R1-R1--1. - The “ibm,model-class” - property must be included in the + The “ibm,model-class” + property must be included in the platform’s root node. @@ -1209,162 +1209,162 @@ ELSE
Security - Platforms will provide the user with options for a Power On Password - (POP) and a Privileged Access Password (PAP) and will have some optional + Platforms will provide the user with options for a Power On Password + (POP) and a Privileged Access Password (PAP) and will have some optional physical security features. - R1-R1--1. - Platform - Implementation: Platforms must provide a Power On - Password (POP) capability which, when enforced, controls the - user’s ability to power-on and execute the configured boot + Platform + Implementation: Platforms must provide a Power On + Password (POP) capability which, when enforced, controls the + user’s ability to power-on and execute the configured boot sequence. - + - R1-R1--2. - Platform - Implementation: Platforms must provide a Privileged - Access Password (PAP) capability which, when enforced, controls the - user’s ability to alter the boot sequence using f5/f6, and to enter SMS + Platform + Implementation: Platforms must provide a Privileged + Access Password (PAP) capability which, when enforced, controls the + user’s ability to alter the boot sequence using f5/f6, and to enter SMS and the Multiboot Menu. - + - R1-R1--3. - Platform - Implementation: If the PAP is absent or <NULL>, but the POP is + Platform + Implementation: If the PAP is absent or <NULL>, but the POP is non-<NULL>, then the POP must act as the PAP. - + - R1-R1--4. - Platform - Implementation: Platforms must accept the PAP as a valid response to + Platform + Implementation: Platforms must accept the PAP as a valid response to a request to enter the POP. - + - R1-R1--5. - Platform Implementation: If - there is a key switch implemented with a secure position, the - system must not complete the boot process regardless of the state of POP and + Platform Implementation: If + there is a key switch implemented with a secure position, the + system must not complete the boot process regardless of the state of POP and PAP when the switch is in this position. - + - R1-R1--6. - Platform - Implementation: If a key switch is implemented and the switch is in - the maintenance (service) position, the POP and PAP must + Platform + Implementation: If a key switch is implemented and the switch is in + the maintenance (service) position, the POP and PAP must not be enforced. - + - R1-R1--7. - Platform - Implementation: Platforms, except for rack mounted systems, must - provide a locking mechanism as an option which prevents the removal of the + Platform + Implementation: Platforms, except for rack mounted systems, must + provide a locking mechanism as an option which prevents the removal of the covers. - + - R1-R1--8. - Platform Implementation: Platforms, except for rack mounted systems, must - provide a tie-down mechanism as an option which prevents the physical removal + Platform Implementation: Platforms, except for rack mounted systems, must + provide a tie-down mechanism as an option which prevents the physical removal of the system from the premises. - + - R1-R1--9. - Platform Implementation: Passwords and keyswitch positions must be - implemented in a manner that makes their values accessible to both OF and the + Platform Implementation: Passwords and keyswitch positions must be + implemented in a manner that makes their values accessible to both OF and the service processor. - + - R1-R1--10. - Platform Implementation: The OF configuration variable - security-password must be maintained to be equivalent to the + Platform Implementation: The OF configuration variable + security-password must be maintained to be equivalent to the Privileged Access Password (PAP). - + - R1-R1--11. - Platform - Implementation: If the PAP and security-password - are absent or <NULL>, security-mode must be set to - “none”, otherwise security-mode + Platform + Implementation: If the PAP and security-password + are absent or <NULL>, security-mode must be set to + “none”, otherwise security-mode must be set to “command”. - + - R1-R1--12. - Platform Implementation: If security-mode - is set to any value other than “none” (such as - “command” or “full”), + Platform Implementation: If security-mode + is set to any value other than “none” (such as + “command” or “full”), it must be treated as security-mode=command. Platform Implementation Notes: - + - As defined here, the PAP and security-password are - stronger than as specified in IEEE 1275 for - security-mode = command in that - they are required for any command line operations, including - go and - boot. The PAP and - security-password are not required to boot the system with default - parameters, however, and in this sense the intent of - security-mode = command is achieved. There is currently no - implementation of + As defined here, the PAP and security-password are + stronger than as specified in IEEE 1275 for + security-mode = command in that + they are required for any command line operations, including + go and + boot. The PAP and + security-password are not required to boot the system with default + parameters, however, and in this sense the intent of + security-mode = command is achieved. There is currently no + implementation of security-mode = full. - If a service processor is provided, the requirements relating to - passwords are applicable in the service processor environment. Service - processor documentation refers to the POP as the General User Password and the + If a service processor is provided, the requirements relating to + passwords are applicable in the service processor environment. Service + processor documentation refers to the POP as the General User Password and the PAP as the Privileged User Password. - + @@ -1372,32 +1372,32 @@ ELSE
Endian Support - LoPAR platforms operate with either Big-Endian (BE) or Little-Endian - (LE) addressing. In Big-Endian systems, the address of a word in memory is the - address of the most significant byte (the “big” end) of the word. - Increasing memory addresses will approach the least significant byte of the - word. In Little-Endian (LE) addressing, the address of a word in memory is the - address of the least significant byte (the “little” end) of the + LoPAR platforms operate with either Big-Endian (BE) or Little-Endian + (LE) addressing. In Big-Endian systems, the address of a word in memory is the + address of the most significant byte (the “big” end) of the word. + Increasing memory addresses will approach the least significant byte of the + word. In Little-Endian (LE) addressing, the address of a word in memory is the + address of the least significant byte (the “little” end) of the word. - All data structures used for communicating between the OS and the - platform (for example, RTAS and hypervisor calls) are Big-Endian format, unless + All data structures used for communicating between the OS and the + platform (for example, RTAS and hypervisor calls) are Big-Endian format, unless otherwise designated. - R1-R1--1. Platforms must by default operate with Big-Endian addressing. - + - R1-R1--2. - Platforms that operate with Little-Endian addressing must make - System memory appear to be in Little-Endian format to all entities in the + Platforms that operate with Little-Endian addressing must make + System memory appear to be in Little-Endian format to all entities in the system that may observe that image, including I/O. @@ -1405,101 +1405,101 @@ ELSE Platform Implementation Notes: - + - Some hardware (for example, bridges, memory controllers, and - processors) may have modal bits to allow those components to be used in - platforms which operate in Little-Endian mode. In this case, the hardware or + Some hardware (for example, bridges, memory controllers, and + processors) may have modal bits to allow those components to be used in + platforms which operate in Little-Endian mode. In this case, the hardware or firmware will need to set those bits appropriately. - Requirement may have an + Requirement may have an impact on the processor chosen for the platform. - +
64-Bit Addressing Support - A 64-bit-addressing-capable platform is defined as one capable of - supporting System Memory and Memory Mapped I/O (MMIO) configured above 4 GB - (greater than 32 bits of real addressing). This means that all hardware - elements in the topology down to the Host Bridges are capable of dealing with a - real address range greater than 32 bits, and all Host Bridges are capable of - providing a translation mechanism for translating 32-bit I/O bus DMA addresses. - All platforms compliant with IBM - Power Architecture Platform Requirements (PAPR) version 2.3 and beyond are required to be + A 64-bit-addressing-capable platform is defined as one capable of + supporting System Memory and Memory Mapped I/O (MMIO) configured above 4 GB + (greater than 32 bits of real addressing). This means that all hardware + elements in the topology down to the Host Bridges are capable of dealing with a + real address range greater than 32 bits, and all Host Bridges are capable of + providing a translation mechanism for translating 32-bit I/O bus DMA addresses. + All platforms compliant with IBM + Power Architecture Platform Requirements (PAPR) version 2.3 and beyond are required to be 64-bit-addressing-capable. - A 64-bit-addressing-aware OS is an OS that can deal with a real - address space larger than 4GB. It must handle the 64-bit processor page table - format (required of all OSs), and must understand Host Bridge mechanisms and - Host Bridge OF methods for supporting System Memory greater than 4 GB. All OSs - compliant with IBM - Power Architecture Platform Requirements (PAPR) version 2.3 and beyond are required to be + A 64-bit-addressing-aware OS is an OS that can deal with a real + address space larger than 4GB. It must handle the 64-bit processor page table + format (required of all OSs), and must understand Host Bridge mechanisms and + Host Bridge OF methods for supporting System Memory greater than 4 GB. All OSs + compliant with IBM + Power Architecture Platform Requirements (PAPR) version 2.3 and beyond are required to be 64-bit-addressing-aware.
Minimum System Requirements - This section - summarizes the minimum hardware and functionality required for LoPAR + This section + summarizes the minimum hardware and functionality required for LoPAR compliance. - The - term portable is used in this document to describe that class of systems that + The + term portable is used in this document to describe that class of systems that is primarily battery powered and is easily carried by its user. - The term personal is used in this document to describe that class of systems that - is bound to a specific work area due to its size or power source, and whose use + The term personal is used in this document to describe that class of systems that + is bound to a specific work area due to its size or power source, and whose use is generally restricted to a single direct user or a small set of users. - The term server is used in this document to describe that class of systems that - supports a multi-user environment, providing a particular service such as file + The term server is used in this document to describe that class of systems that + supports a multi-user environment, providing a particular service such as file storage, software repository, or remote processing capability. - Each of these classes may have unique requirements due to the way it - is used or which OS it generally employs and, for this reason, the requirements - in this document my have qualifiers based on the type of system being + Each of these classes may have unique requirements due to the way it + is used or which OS it generally employs and, for this reason, the requirements + in this document my have qualifiers based on the type of system being developed. - R1-R1--1. - (Requirement moved to + (Requirement moved to ) - + - R1-R1--2. - A means of attaching a diskette drive must be - provided (may be through a connector or over a network) and the drive must have + A means of attaching a diskette drive must be + provided (may be through a connector or over a network) and the drive must have the following characteristics: - + - Media sense: Implementations must allow polling of the drive up to + Media sense: Implementations must allow polling of the drive up to 100x per second to determine the presence of media in the drive. Must accept media of type: 3.5" 1.44 MB MFM - + - + - R1-R1--3. - A means of attaching a CD-ROM drive must be - provided (may be through a connector or over a network) and the drive must have + A means of attaching a CD-ROM drive must be + provided (may be through a connector or over a network) and the drive must have the following characteristics: - + ISO9600 compliant @@ -1507,47 +1507,47 @@ ELSE Supports multi-session - + - + - R1-R1--4. - When a keyboard is provided, it must be + When a keyboard is provided, it must be capable of generating at least 101 scan codes. - + - R1-R1--5. - When a mouse is provided, it must have at + When a mouse is provided, it must have at least two buttons. - + - R1-R1--6. - The capability to generate a tone must be provided on portable - and personal platforms, and on server platforms which are not housed in rack + The capability to generate a tone must be provided on portable + and personal platforms, and on server platforms which are not housed in rack enclosures. - + - R1-R1--7. - A Real Time Clock (RTC) must be + A Real Time Clock (RTC) must be provide which must have the following characteristics: - + Is non-volatile @@ -1559,7 +1559,7 @@ ELSE Has a resolution of at least one second - + @@ -1568,42 +1568,42 @@ ELSE
Options and Extensions - Options are features that are covered by this architecture, but are - not necessarily required to be present on a given platform. Platforms that - implement options are required to conform to the definitions in this - architecture, so that an aware OS environment can recognize and support them. - Some options may be required on some platforms. Refer to - for the disposition of currently defined - options, including requirements for implementation of some of these options on - some platforms. Note that in this table, “optional” does not mean - “not required;” see the description column of the table for more + Options are features that are covered by this architecture, but are + not necessarily required to be present on a given platform. Platforms that + implement options are required to conform to the definitions in this + architecture, so that an aware OS environment can recognize and support them. + Some options may be required on some platforms. Refer to + for the disposition of currently defined + options, including requirements for implementation of some of these options on + some platforms. Note that in this table, “optional” does not mean + “not required;” see the description column of the table for more information. - An extension is a feature that is added to this architecture and is + An extension is a feature that is added to this architecture and is required on all platforms developed after a specified effective date. - Options and extensions will normally need to be dormant or invisible - in the presence of a non-aware OS environment. In general, this means that they - come up passively; that is, they are initialized to an inactive state and + Options and extensions will normally need to be dormant or invisible + in the presence of a non-aware OS environment. In general, this means that they + come up passively; that is, they are initialized to an inactive state and activated by an aware OS. - R1-R1--1. - Extensions and options must come up + Extensions and options must come up passively unless otherwise specified in this architecture. - + - R1-R1--2. - Extensions and options that affect the OS - interface to the platform must be identified, when present, through some + Extensions and options that affect the OS + interface to the platform must be identified, when present, through some architected means, such as OF device tree properties. - It is the responsibility of the product development teams to keep the - “usage” columns of up + It is the responsibility of the product development teams to keep the + “usage” columns of up to date, @@ -1649,8 +1649,8 @@ ELSE - Usage Legend : NS = - Not Supported; O = Optional (see also Description); OR = Optional but + Usage Legend : NS = + Not Supported; O = Optional (see also Description); OR = Optional but Recommended; R = Required; SD = See Description @@ -1724,9 +1724,9 @@ ELSE R - See and - . Requirements for platforms that implement - LPAR, regardless of the number of partitions, are contained in + See and + . Requirements for platforms that implement + LPAR, regardless of the number of partitions, are contained in . @@ -1769,8 +1769,8 @@ ELSE R - EEH support for I/O structures which contain PCI to PCI - bridges or PCI Express switches. See . + EEH support for I/O structures which contain PCI to PCI + bridges or PCI Express switches. See . Required if EEH is supported. @@ -1801,7 +1801,7 @@ ELSE O - See for more information on + See for more information on support of I2C buses. @@ -1872,8 +1872,8 @@ ELSE R - The Converged Location Codes option is required on all - platforms being developed. and + The Converged Location Codes option is required on all + platforms being developed. and Requirement . @@ -2014,7 +2014,7 @@ ELSE NS - and "Managing + and "Managing Storage Preservations" in specification. @@ -2029,10 +2029,10 @@ ELSE R - Required of all platforms that support LPAR, otherwise not - implemented. Provides a virtual “Asynchronous” IOA for connecting - to a server Vterm IOA, the hypervisor, or HMC (for example, to a virtual - console). See for more + Required of all platforms that support LPAR, otherwise not + implemented. Provides a virtual “Asynchronous” IOA for connecting + to a server Vterm IOA, the hypervisor, or HMC (for example, to a virtual + console). See for more information. @@ -2047,7 +2047,7 @@ ELSE O - Allows a partition to serve a partner partition's client + Allows a partition to serve a partner partition's client Vterm IOA. @@ -2077,8 +2077,8 @@ ELSE NS - Provides access to platform-level facilities for - performance tools running in a partition on an LPAR system. See + Provides access to platform-level facilities for + performance tools running in a partition on an LPAR system. See . @@ -2149,8 +2149,8 @@ ELSE O - Allows a partition to sleep for an extended period; during - this time the partition state is stored on secondary storage for later + Allows a partition to sleep for an extended period; during + this time the partition state is stored on secondary storage for later restoration. Requires the Partition Suspension, ILLAN, and VASI options. @@ -2165,9 +2165,9 @@ ELSE O - Allows the movement of a logical partition from one - platform to another; the source and destination platforms cooperate to minimize - the time that the partition is non-responsive. Requires the Partition + Allows the movement of a logical partition from one + platform to another; the source and destination platforms cooperate to minimize + the time that the partition is non-responsive. Requires the Partition Suspension, ILLAN, and VASI options. @@ -2182,7 +2182,7 @@ ELSE O - Allows the multi-threaded caller to efficiently establish + Allows the multi-threaded caller to efficiently establish a single threaded processing environment. @@ -2197,8 +2197,8 @@ ELSE O - Allows the caller to determine which device tree nodes - changed due to a massive platform reconfiguration as happens during a partition + Allows the caller to determine which device tree nodes + changed due to a massive platform reconfiguration as happens during a partition migration or hibernation. @@ -2214,9 +2214,9 @@ ELSE O - Allows an authorized virtual server partition (VSP) to - safely access the internal state of a specific partition. See - for more details. Requires the Reliable + Allows an authorized virtual server partition (VSP) to + safely access the internal state of a specific partition. See + for more details. Requires the Reliable Command/Response Transport option. @@ -2231,7 +2231,7 @@ ELSE O - Allows the OS to dynamically relocate, expand, and shrink + Allows the OS to dynamically relocate, expand, and shrink the Real Mode Area. @@ -2246,8 +2246,8 @@ ELSE O - Allows the OS to indicate that there is no need to search - secondary page table entry groups to determine a page table search has failed. + Allows the OS to indicate that there is no need to search + secondary page table entry groups to determine a page table search has failed. See for more details. @@ -2262,7 +2262,7 @@ ELSE O - Allows the OS to register and unregister kernel dump + Allows the OS to register and unregister kernel dump information with the platform. @@ -2291,7 +2291,7 @@ ELSE O - Support for the Subordinate CRQs as needed by some Virtual + Support for the Subordinate CRQs as needed by some Virtual IOAs. See . @@ -2306,8 +2306,8 @@ ELSE O - The CMO option allows for partition participation in the - over-commitment of logical memory by the platform. See + The CMO option allows for partition participation in the + over-commitment of logical memory by the platform. See . @@ -2322,7 +2322,7 @@ ELSE O - Allows the OS to cooperate with platform energy + Allows the OS to cooperate with platform energy management. See . @@ -2337,7 +2337,7 @@ ELSE O - Support for the Multi-TCE-Table Option. See + Support for the Multi-TCE-Table Option. See . @@ -2352,8 +2352,8 @@ ELSE O - Provides substantially consistent virtual processor - associativity in a shared processor LPAR environment. See + Provides substantially consistent virtual processor + associativity in a shared processor LPAR environment. See . @@ -2396,7 +2396,7 @@ ELSE O - Allows OS notification of a cooperative memory + Allows OS notification of a cooperative memory overcommitment page fault see . @@ -2411,8 +2411,8 @@ ELSE O - Allows the platform to communicate and the availability of - performance boost modes along with any ability to manage the same. See + Allows the platform to communicate and the availability of + performance boost modes along with any ability to manage the same. See @@ -2444,7 +2444,7 @@ ELSE O - Allows the creation of DMA Windows above 4 GB. See + Allows the creation of DMA Windows above 4 GB. See . @@ -2489,7 +2489,7 @@ ELSE O - Introduces additional cooperative memory overcommitment + Introduces additional cooperative memory overcommitment functions see @@ -2547,10 +2547,25 @@ ELSE O - Provides support for the system wide Memory Management Unit + Provides support for the system wide Memory Management Unit architecture introduced in POWER ISA 3.0 + + + Hash Page Table Resize Option + + + O + + + O + + + Allows partitions to resize their HPT. See + . + + @@ -2558,32 +2573,32 @@ ELSE
IBM LoPAR Platform Implementation Requirements - The tables in this section detail specific product requirements which - are not defined as an “option” in this architecture. The intent - is to define base requirements for these products, over and beyond what is - specified in and elsewhere in this + The tables in this section detail specific product requirements which + are not defined as an “option” in this architecture. The intent + is to define base requirements for these products, over and beyond what is + specified in and elsewhere in this architecture. - In addition, any options that are unique to specific implementations - (that is, not general usage), and which do not appear in + In addition, any options that are unique to specific implementations + (that is, not general usage), and which do not appear in , are listed in this section. - It is the responsibility of the product development teams to keep + It is the responsibility of the product development teams to keep these tables up to date.
IBM Server Requirements - This section talks to the requirements for IBM LoPAR Compliant + This section talks to the requirements for IBM LoPAR Compliant server platforms. - R1-R1--1. - For all IBM LoPAR Compliant - Platforms: The platform must implement the options marked as - “required” in the IBM Server column of - and the additional functions as indicated - in (that is, the “Base” + For all IBM LoPAR Compliant + Platforms: The platform must implement the options marked as + “required” in the IBM Server column of + and the additional functions as indicated + in (that is, the “Base” column of is not sufficient). @@ -2629,50 +2644,50 @@ ELSE - It is the responsibility of the product development teams to keep + It is the responsibility of the product development teams to keep up to date.
Behavior for Optional and Reserved Bits and Bytes - Behavior of the OSs and platforms for bits and bytes in this + Behavior of the OSs and platforms for bits and bytes in this architecture that are marked as reserved or optional are defined here. - R1-R1--1. - Bits and bytes which are marked as - “optional” by this architecture and which are not implemented by - the platform must be ignored by the platform on a Store - and must be returned as 0’s on a Load, including + Bits and bytes which are marked as + “optional” by this architecture and which are not implemented by + the platform must be ignored by the platform on a Store + and must be returned as 0’s on a Load, including the reserved or optional bits of a partially implemented field. - + - R1-R1--2. - Bits and bytes which are marked as - “reserved” by this architecture must be ignored by the platform - on a Store and must be returned as 0’s on a - Load, except that bits that are marked as - “reserved” and which were previously defined by the architecture - maybe be treated appropriately by legacy hardware (such bits in this + Bits and bytes which are marked as + “reserved” by this architecture must be ignored by the platform + on a Store and must be returned as 0’s on a + Load, except that bits that are marked as + “reserved” and which were previously defined by the architecture + maybe be treated appropriately by legacy hardware (such bits in this architecture will state the value that software must use henceforth). - + - R1-R1--3. - Bits and bytes marked as - “reserved” must be set to 0 by the OS on a - Store, except as otherwise defined by the architecture, and must be + Bits and bytes marked as + “reserved” must be set to 0 by the OS on a + Store, except as otherwise defined by the architecture, and must be ignored on a Load. diff --git a/Virtualization/ch_lpar_option.xml b/Virtualization/ch_lpar_option.xml index 773fc4b..2f1fc94 100644 --- a/Virtualization/ch_lpar_option.xml +++ b/Virtualization/ch_lpar_option.xml @@ -1,7 +1,7 @@ Logical Partitioning Option - +
Overview The Logical PARtitioning option (LPAR) simultaneously runs one or @@ -14,7 +14,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo generates an OF device tree to represent the resources of the partition to the OS image. Allocatable resources are directly controlled by an OS. This architecture restricts the sharing of allocatable resources between - partitions; to do so requires the use of optional facilities presented in + partitions; to do so requires the use of optional facilities presented in . Platform resources, other than allocatable resources mentioned above, that are represented by OF nodes in the device tree of more than one partition (for example, memory controllers @@ -36,7 +36,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo “Real Mode” addressing mode, in these processors, is redefined to translate and limit the physical addresses that the processor can access and to restrict access to certain address translation controlling processor - resources. The virtual addressing mode is unchanged. See the + resources. The virtual addressing mode is unchanged. See the (level 2.0 and beyond) for the architecture extensions required for the processor. The I/O subsystems of these platforms contain I/O bridges that @@ -81,11 +81,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo configuration is stored in the platform and, therefore, the HMC is not required to boot or operate the platform in a pre-configured non-error condition. - +
Real Mode Accesses When the OS controlling an LPAR runs with address translation - turned off (MSRDR or MSRIR + turned off (MSRDR or MSRIR bit(s) =0) (real mode) the LPAR hardware translates the memory addresses to an LPAR unique area known as the Real Mode Area (RMA). When control is initially passed to the OS from the @@ -96,7 +96,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo an storage interrupt (ISI/DSI depending upon instruction or data reference). The RMA hardware translation scheme is platform dependent. The options are given below. - +
Offset and Limit Registers The Offset RMA architecture checks the LPAR effective address @@ -104,7 +104,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo adding an LPAR specific offset to form the real address, if the effective address is less, else signaling a protection exception.
- +
Reserved Virtual Addresses The platform may map the RMA through the hashed paged table via a @@ -118,20 +118,20 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo the real storage blocks that make up the RMA. Note, this method allows for the RMA to be discontiguous in real address space. The Virtualized Real Mode Area (VRMA) option gives the OS the ability to dynamically - relocate, expand, and shrink the RMA. See + relocate, expand, and shrink the RMA. See for more details.
- +
General LPAR Reservations and Conventions This section documents general LPAR reserved facilities and conventions. Other sections document reserved facilities and conventions specific to the function they describe. - + - R1-R1--1. For the LPAR option: To avoid conflict with the @@ -140,9 +140,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo than virtualizing the RMA. - + - R1-R1--2. For the LPAR option: In order to avoid a storage @@ -152,9 +152,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to access the virtual address space. - + - R1-R1--3. For the LPAR option: To avoid conflict with the @@ -163,9 +163,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo machine check or reset interrupt is taken. - + - R1-R1--4. For the LPAR option: If the platform virtualizes the @@ -174,9 +174,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo entry per page table entry group to virtualize the RMA. - + - R1-R1--5. For the LPAR option: If the platform virtualizes the @@ -186,40 +186,40 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - +
- +
Processor Requirements - + - R1-R1--1. For the LPAR option: The platform processors must - support the Logical Partitioning (LPAR) facilities as defined in + support the Logical Partitioning (LPAR) facilities as defined in (Version 2.0 or later). - - + +
- +
I/O Sub-System Requirements The platform divides the I/O subsystem up into Partitionable - Endpoints (PEs). See + Endpoints (PEs). See for more information on PEs. Each PE has its own (separate) error, addressing, and interrupt domains which allows the assignment of separate PEs to different LPAR partitions. The following are the requirements for I/O subsystems when the platform implements LPAR. - + - R1-R1--1. For the LPAR option: The platform must provide methods @@ -230,9 +230,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo the EEH option programming model. - + - R1-R1--2. For the LPAR option: @@ -240,44 +240,44 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Software and Firmware Implementation Notes: For the platform (versus the OS or device driver) to enable EEH, there must be some assurance that the device drivers are EEH aware, if not EEH enabled. For - example, the device driver or OS may signal its awareness by using + example, the device driver or OS may signal its awareness by using ibm,set-eeh-option RTAS call to enable EEH prior to a - configuration cycle via the + configuration cycle via the ibm,write-pci-config RTAS call which enables the Memory Space or IO Space enable bits in the PCI Command register, and firmware can - ignore the + ignore the ibm,write-pci-config RTAS call which enables the Memory Space or IO Space enable bits for an IOA if EEH for that IOA has not been enabled first. To be EEH aware, a device driver does not need to be able to recover from an MMIO Stopped and DMA Stopped state, only recognize the - all-1's condition (from a + all-1's condition (from a Load from its IOA or on a PCI configuration read from its IOA) and not use data from operations that may have occurred since the last all-1's checkpoint. In addition, the device driver under such failure - circumstances needs to turn off interrupts (using the + circumstances needs to turn off interrupts (using the ibm,set-int-off RTAS call, or for conventional PCI and - PCI-X infrastructures only: by resetting the IOA and keeping it reset with - ibm,set-slot-reset or + PCI-X infrastructures only: by resetting the IOA and keeping it reset with + ibm,set-slot-reset or ibm,slot-error-detail) to make sure that any (unserviceable) interrupts from the IOA do not affect the system (MSIs are blocked by the EEH DMA Stopped State, but LSIs are not). Note that if - all-1’s data may be valid, the + all-1’s data may be valid, the ibm,read-slot-reset-state2 RTAS call should be used to discover the true EEH state of the device. - + - R1-R1--3. For the LPAR option: The platform must assign a PE to one and only one partition at a time. - + - R1-R1--4. For the LPAR option: @@ -287,19 +287,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo ranges. Architecture and Implementation Notes: - + - Platforms which do not implement either Requirement - or Requirement + Platforms which do not implement either Requirement + or Requirement require PE granularity of everything below the PHB, resulting in poor LPAR partition I/O assignment granularity. - Requirement + Requirement has implications in preventing access to both to I/O address - ranges and system memory address ranges. That is, Requirement + ranges and system memory address ranges. That is, Requirement requires prevention of peer to peer operations from one IOA to @@ -310,13 +310,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo use of such bridges or switches require the limitation that all IOAs under such bridges or switches be assigned to the same partition. - + - + - R1-R1--5. For the LPAR option: The platform must @@ -324,66 +324,66 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo assigned to the partition to which the PE is allocated. - + - R1-R1--6. For the LPAR option: If TCEs are used to satisfy - Requirements - , and + Requirements + , and , then the platform must provide the capability to map simultaneously and at all times at least 256 MB for each PE. - + - R1-R1--7. For the LPAR option: If TCEs are used to satisfy - Requirements - , and + Requirements + , and , then the platform must prevent any DMA operations to System Memory addresses which are not translated by TCEs. - + - R1-R1--8. For the LPAR option: The DMA address range accessible - to a PCI IOA on its I/O bus must be defined by the + to a PCI IOA on its I/O bus must be defined by the “ibm,dma-window” property in its parent’s OF device tree node. Platform Implementation Note: To maximize the ability to migrate memory pages underneath active DMA operations, when ever possible, a bridge should create a bus for a single IOA and either its representing bridge - node should include the + node should include the “ibm,dma-window” property specific for the IOA for conventional PCI or PCI-X IOAs or the IOA function nodes should - contain the + contain the “ibm,my-dma-window” property specific for the IOA function for PCI Express IOAs. When the configuration of a bus precludes memory migration, the platform may combine the DMA address for - multiple IOAs that share a bus into a single + multiple IOAs that share a bus into a single “ibm,dma-window” property housed in the bridge node representing the bridge that creates the shared bus. - +
- +
Interrupt Sub-System Requirements - R1-R1--1. For the LPAR option: The platform must @@ -391,9 +391,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to different PEs (interrupts cannot be shared between partitions). - + - R1-R1--2. For the LPAR option: The interrupt presentation layer @@ -401,9 +401,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partition. - + - R1-R1--3. For the LPAR option: The interrupt presentation layer @@ -413,9 +413,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partitions. - + - R1-R1--4. For the LPAR option: The platform must restrict the @@ -423,9 +423,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partition. - + - R1-R1--5. For the LPAR option: If the interrupt source layer @@ -434,9 +434,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo platform’s address space. - + - R1-R1--6. For the LPAR option: If the interrupt source layer @@ -444,9 +444,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to the PMIP’s 4 K page except those to the PMIP itself. - + - R1-R1--7. For the LPAR option: If the interrupt source layer @@ -456,9 +456,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo that returns all 1s as above is optional. - + - R1-R1--8. For the LPAR option: The interrupt source layer must @@ -474,9 +474,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - +
- +
Hypervisor Requirements The purpose of the hypervisor is to virtualize the facilities of @@ -1595,21 +1595,41 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Manage the virtual address translation mode including registration of a process table. + + + + / + + + + Prepares for resizing the partition's HPT + + + + + + / + + + + Changes the partition's HPT to a new size + + - +
System Reset Interrupt Hypervisor code saves all processor state by saving the contents of - one register in SPRG2 (SPRG1 if + one register in SPRG2 (SPRG1 if ibm,nmi-register-2 was used) (Multiplexing the use of this resource with the OS). The processor’s stack and data area are found by processing the Processor Identification Register. - R1-R1--1. For the LPAR option: The platform must support @@ -1617,9 +1637,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partition. - + - R1-R1--2. For the LPAR option: The platform must support @@ -1627,9 +1647,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to all supported partitions. - + - R1-R1--3. For the LPAR option: The system reset interrupts @@ -1637,27 +1657,27 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partition. - + - R1-R1--4. For the LPAR option: The hypervisor must intercept all system reset interrupts. - + - R1-R1--5. For the LPAR option: The platform must implement the FWNMI option. - + - R1-R1--6. For the LPAR option: The hypervisor must maintain a @@ -1666,9 +1686,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to a partition’s processor. - + - R1-R1--7. For the LPAR option: Once the partition’s OS @@ -1677,9 +1697,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partition’s processor. - + - R1-R1--8. For the LPAR option: The hypervisor must on the third @@ -1688,9 +1708,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo reboot policy. - + - R1-R1--9. For the LPAR option: @@ -1702,11 +1722,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
- +
Machine Check Interrupt Hypervisor code saves all processor state by saving the contents of - one register in SPRG2 (SPRG1 if + one register in SPRG2 (SPRG1 if ibm,nmi-register-2 was used) (Multiplexing the use of this resource with the OS). The processor’s stack and data area are found by processing the Processor Identification Register. @@ -1720,7 +1740,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--1. For the LPAR option: The hypervisor must have the @@ -1732,7 +1752,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
- +
Hypervisor Call Interrupt The hypervisor call (hcall) interrupt is a special variety of the @@ -1743,23 +1763,23 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo parameters cause. Some input parameters are indexes. Output parameters, when generated, are passed in registers 4 through 12 and require special in-line assembler code on the part of the caller. The first parameter to - hcall() is the function token. + hcall() is the function token. specifies the valid hcall() function names and token values. Some of the hcall() functions are optional, to indicate if the platform is in LPAR mode, and which - functions are available on a given platform, the OF property + functions are available on a given platform, the OF property “ibm,hypertas-functions” is provided in the /rtas node of the partition’s device tree. The property is present if the platform is in LPAR mode while its value specifies which function sets are implemented by a given implementation. If platform implements any hcall() of a function set it implements the - entire function set. Additionally, certain values of the + entire function set. Additionally, certain values of the “ibm,hypertas-functions” property indicate that the platform supports a given architecture extension to a standard hcall(). The floating point registers along with the FPSCR are in general preserved across hcall() functions, unless the “Maintain - FPRs” field of the VPA =0, see + FPRs” field of the VPA =0, see . The general purpose registers r0 and r3-r12, the CTR and XER registers are volatile along with the condition register fields 0 and 1 plus 5-7. Specific hcall()s may specify @@ -1768,24 +1788,24 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--1. - For the LPAR option: The platform’s - /rtas node must contain an + For the LPAR option: The platform’s + /rtas node must contain an “ibm,hypertas-functions” property as defined below. - + - R1-R1--2. - For the LPAR option: If a platform reports in its - “ibm,hypertas-functions” property (see + For the LPAR option: If a platform reports in its + “ibm,hypertas-functions” property (see ) that it supports a function set, then it - must support all hcall()s of that function set as defined in + must support all hcall()s of that function set as defined in . @@ -3242,7 +3262,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + / @@ -3261,7 +3281,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + / @@ -3605,7 +3625,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo an optional dash delimited series (may be null) of supported resource codes encoded as ASCII decimal values in addition to the minimal support value of 1 for processors, other values - are define in + are define in . @@ -3977,7 +3997,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Reserved - 0x35C-0x370 + 0x35C-0x368   @@ -3989,6 +4009,44 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo   + + + + / + + + + 0x36C + + + Normal + + + If the platform supports the Hash Page Table Resize Option + + + hcall-hpt-resize + + + + + + / + + + + 0x370 + + + Normal + + + If the platform supports the Hash Page Table Resize Option + + + hcall-hpt-resize + + @@ -4065,7 +4123,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - Reserved for platform-dependent hcall()s / + Reserved for platform-dependent hcall()s / @@ -4168,25 +4226,25 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--3. For the LPAR option: The caller must perform properly given that the hypervisor meets the performance class specified. - + - R1-R1--4. For the LPAR option: The hypervisor implementation must meet the specified performance class or higher. - + - R1-R1--5. For the LPAR option: Platform hardware designs must @@ -4194,9 +4252,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo hardware access technology for the various facilities. - + - R1-R1--6. For the LPAR option: The hypervisor must have the @@ -4205,14 +4263,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo up to the number of processors in the system. - + - R1-R1--7. For the LPAR option: The hypervisor must check the state of the MSR register bits that are not set to a specific value by - the processor hardware during the invoking interrupt per + the processor hardware during the invoking interrupt per . @@ -4306,19 +4364,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--8. For the LPAR option: The Hcall() flags field must - meet the definition in: + meet the definition in: ; the hypervisor may safely ignore flag field values not explicitly defined by the specific hcall() semantic. - + - R1-R1--9. For the LPAR option: The platform must ensure that @@ -4326,9 +4384,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo partitioning integrity. - + - R1-R1--10. For the LPAR option: Implementations that normally @@ -4453,9 +4511,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo key0-key4 Bits 50-54 (key0 - key4) shall be treated as reserved - on platforms that either do not contain an + on platforms that either do not contain an “ibm,processor-storage-keys” property, - or contain an + or contain an “ibm,processor-storage-keys” property with the value of zero in both cells. @@ -4470,7 +4528,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Bit 55 (pp0) shall be treated as reserved on platforms that do not have the “Support for the “110” value of the Page Protection (PP) bits” bit set to a - value of 1 in the + value of 1 in the “ibm,pa-features” property. @@ -4547,8 +4605,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo MUI Options - Bits 43-46 (MUI Options) detail is provided in - + Bits 43-46 (MUI Options) detail is provided in + in . @@ -4597,28 +4655,28 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--11. For the LPAR option: The caller of Hcall must be in privileged mode (MSRPR = 0) or the hypervisor immediately returns an - H_Privilege return code. See + H_Privilege return code. See for this and other architected return codes. - + - R1-R1--12. For the LPAR option: The caller of hcall() must be prepared for a return code of H_Hardware from all functions. - + - R1-R1--13. For the LPAR option: @@ -4627,7 +4685,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo an undetectable state/data corruption as a result of the original error. Notes: - + A detectable corruption, when accessed, results in either a H_Hardware return code, machine check or check stop per platform @@ -4635,7 +4693,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - Among other implications of Requirement + Among other implications of Requirement are: the effective state of the partition appears to not change due to the failed hcall() -- (any partial changes to persistent state/data are backed out); and the recovery of @@ -4650,7 +4708,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo serviceable event in response to the underlying cause is handled by separate platform initiated operations. - + @@ -5471,7 +5529,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
- +
Hypervisor Call Functions @@ -5480,11 +5538,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Page Frame Table Access All hypervisor Page Frame Table (PFT) access routines are called using 64 bit linkage conventions and apply to all page sizes that the - platform supports as specified by the - “ibm,processor-page-sizes” property. (See - for more details.) + platform supports as specified by the + “ibm,processor-page-sizes” property. (See + for more details.) The Page actual size is encoded in the PFT entry - per the architecture Book IIIs along with the + per the architecture Book IIIs along with the segment base page size per the Book IVa. The hypervisor PFT @@ -5524,16 +5582,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo in the high order 16 bits of the flags parameter (H_ENTER and H_READ only) or by issuing the hcall() from a processor within the translation domain as identified by the processor’s NUMA CEC Cookie field of - the + the “ibm,pft-size” property. The PFT is preallocated based upon the value of the partition’s PFT_size configuration variable. This configuration variable is initialized to 4 PTEs per node local page frame and 2 PTEs per remote node page frame. The size of the PFT per node is communicated - to the partition’s OS image via the + to the partition’s OS image via the “ibm,pft-size” property of the node. - The value of the configuration variable + The value of the configuration variable PFT_size consists of two comma separated integers, the first is the number of hardware PFT entries to allocate per CEC local page, and the second is the number of hardware PFT entries to allocate @@ -5545,7 +5603,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--1. For the LPAR option: The platform must allocate the @@ -5554,21 +5612,21 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo “common” NVRAM partition. - + - R1-R1--2. - For the LPAR option: The platform must provide the + For the LPAR option: The platform must provide the “ibm,pft-size” property in the processor - nodes of the device tree (children of type + nodes of the device tree (children of type cpu of the /cpus node). Register Linkage (For hcall() tokens 0x04 - 0x18) - + On Call: @@ -5588,9 +5646,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + Semantics checks for all hypervisor PTE access routines: - + Hypervisor checks that the caller was in privileged mode or @@ -5603,18 +5661,18 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo assigned to the partition else return H_Parameter. - + Hypervisor checks that the PTEX is zero or greater and less than the partition maximum, else H_Parameter return code. - + Hypervisor checks the logical address contained in any PTE to be entered into the PFT to insure that it is valid and then translates the logical address into the assigned physical address. - + When hypervisor returns the contents of a PTE, the contents of the RPN are usually architecturally undefined. It is expected that hypervisor implementations leave the contents of this field as it was @@ -5624,7 +5682,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo translated into the LPN prior to return. - + Logical addressing: LPAR adds another level of virtual address translation managed by the hypervisor. The OS is never allowed to use the physical address of @@ -5649,8 +5707,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Logical addresses start at zero. When control is initially passed to the OS from the platform, the first region is the single RMA. The first region has logical region identifier of zero. This first region is - specified by the first address - length pair of the - “reg” property of the + specified by the first address - length pair of the + “reg” property of the /memory node of the OF device tree. Subsequent regions each have their own address - length pair. At initial program load time, the logical region identifiers are sequential starting at zero @@ -5663,7 +5721,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo simple indexed table per partition of the physical addresses associated with the start of each region (in logical region identifier order). At least two special values are recognized: - + The invalid value for those regions that do not have a physical @@ -5705,7 +5763,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--3. For the LPAR option: The OS must make no assumptions @@ -5713,20 +5771,20 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo bits. - + - R1-R1--4. For the LPAR option: Each logical region must have - its own address - length pair in the - “reg” property of the OF + its own address - length pair in the + “reg” property of the OF /memory node. - + - R1-R1--5. For the LPAR option: When control is initially passed @@ -5735,9 +5793,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo with translate off. - + - R1-R1--6. For the LPAR option: When control is initially passed @@ -5745,55 +5803,55 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to a real mode length size supported by the platform. - + - R1-R1--7. For the LPAR option: Each logical region must start and end on a boundary of the largest page size that the - logical region supports (see - “ibm,dynamic-memory” and - “ibm,lmb-page-sizes” in - as well as + logical region supports (see + “ibm,dynamic-memory” and + “ibm,lmb-page-sizes” in + as well as for more details). - + - R1-R1--8. For the LPAR option: The pages that contain the platform’s per processor interrupt management areas or any other - device marked + device marked “used-by-rtas” must not be mapped into the partition virtual address space. - + - R1-R1--9. For the LPAR option: - Each logical region must support all page sizes presented in the - “ibm,processor-page-sizes” property in + Each logical region must support all page sizes presented in the + “ibm,processor-page-sizes” property in that are less than or equal to the - size of the logical region as specified by either the OF standard + size of the logical region as specified by either the OF standard “reg” property of the logical - region’s OF - /memory node, or the + region’s OF + /memory node, or the “ibm,lmb-size” property of the logical - region’s - /ibm,dynamic-reconfiguration-memory node in + region’s + /ibm,dynamic-reconfiguration-memory node in . Implementation Note: 32 bit versions of AIX only support 36 bit logical address memory spaces. Providing such a partition with a larger logical memory address space may cause OS failures. - Implementation Note: Requirement + Implementation Note: Requirement may be met by ensuring that all logical regions start and end on a boundary of the largest page size supported by the platform. @@ -5810,7 +5868,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo that a compression coprocessor is available and the page is small enough to be synchronously compressed. If the compression coprocessor is busy, or the page is too large, the compression can be subsequently performed - using the H_COP_OP hcall() see + using the H_COP_OP hcall() see . If the page contents are compressed, then a checksum may be appended by setting the checksum flag - if the compression flag is not set the checksum flag is @@ -5858,7 +5916,7 @@ hcall ( const uint64 H_REMOVE, flags: AVPN, andcond, and for the CMO option: CMO Option flags as - defined in + defined in and for the PFO option the compression and checksum flags. @@ -5902,188 +5960,188 @@ hcall ( const uint64 H_REMOVE, Semantics: - + Check that the PTEX accesses within the PFT else return H_Parameter - + If the AVPN flag is set, and the AVPN parameter bits 0-56 do not match that of the specified PTE then return H_Not_Found. - + If the andcond flag is set, the AVPN parameter is bit anded with the first double word of the specified PTE, if the result is non-zero, then return H_Not_Found. - + The hypervisor Synchronizes the PTE specified by the PTEX and returns its value - - + + Use the architected “Deleting a Page Table Entry” sequence such that the first double word of the resultant PFT entry is all 0s. - + Use the proper tlbie instruction for the page size within a critical section protected by the proper lock (per large page bit in the specified PTE). - + The synchronized value of the old PTE value ends up in R4 and R5 for return to the caller. - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + - + For the PFO option: If the Compression flag is on: - + Check that the calling partition is authorized to use the compression co-processor else return H_Function. - + If the page is not “main store memory” then return H_UNSUPPORTED_FLAG TBD (value - 312) - + - Check that the page size is <= the compression value in + Check that the page size is <= the compression value in “ibm,max-sync-cop” else return H_Constrained. - + Build CRB for compression of the page size indicated in the PTE - + If the checksum flag is on command that a checksum be built - + Verify that the “out” parameter represents a valid logical real address within the caller’s partition else return H_P3 - + If the “outlen” parameter is non-negative verify that the logical real address of (out + outlen) is a valid logical real address within the same 4K page as the “out” parameter else return H_P4. - + If the “outlen” parameter is negative: - + Verify that the absolute value of outlen meet all of the follow else return H_P4: - + - Is <= the value of + Is <= the value of “ibm,max-sg-len” - + Is an even multiple of 16 - + That out + the absolute value of outlen represents a valid logical real address within the same 4K page as the out parameter. - + - + Verify that each 16 byte scatter gather list entry meets all of the following else return H_SG_LIST: - + Verify that the first 8 bytes represents a valid logical real address within the caller’s partition. - + Verify that the logical real address represented by the sum of the first 8 bytes and the second 8 bytes is a valid logical real address within the same 4K page as the first 8 bytes. - + - + - + For the Shared Logical Resource Option if any of the memory represented by the out/outlen parameters have been rescinded then return H_RESCINDED. - + Fill in the destination DDE list from the converted the out/outlen parameters. - + Issue icswx instruction to execute CRB - + Check coprocessor busy - retry / return H_PARTIAL if execution time expired / return H_COP_HW if compressor is broken - + Wait for coprocessor to complete - + If compressor hardware error return H_COP_HW - + Check that the compressor had enough room to house the compressed image else return H_TOO_BIG - + Save compression block size in R6 - + - + Return H_Success - +
- +
H_ENTER This hcall adds an entry into the page frame table. PTEH and PTEL @@ -6099,14 +6157,14 @@ hcall ( const uint64 H_REMOVE, initialize the page from one or more compressed data blocks and optionally (checksum flag) check the end to end block data integrity prior to adding the entry to the page table. If the compression flag is - not set the checksum flag is ignored. If the Memory Usage Instrumentation + not set the checksum flag is ignored. If the Memory Usage Instrumentation (MUI) option is implemented, flags allow for initializing MUI state for the page when the translation is entered. Syntax: - + - + Parameters: - + Flags - - + + CEC Cookie - + Zero Page: Zero the System Memory page in real mode before placing its mapping into the PTE. This flag is ignored for memory mapped @@ -6158,7 +6216,7 @@ hcall ( const uint64 H_ENTER, page with a size larger than 64 K will result in return code of H_TOO_BIG. - + I-Cache-Invalidate: Issue an icbi etc. instruction sequence to manage the I-Cache coherency of the cachable page. This flag is ignored @@ -6167,7 +6225,7 @@ hcall ( const uint64 H_ENTER, page with a size larger than 64 K will result in return code of H_TOO_BIG. - + I-Cache-Synchronize: Issue dcbst and icbi, etc., instruction sequence to manage the I-Cache coherency of the cachable page. This flag @@ -6176,119 +6234,119 @@ hcall ( const uint64 H_ENTER, this flag for a page with a size larger than 64 K will result in return code of H_TOO_BIG. - + Exact: Place the entry in the exact PTE specified by PTEX if it is empty else return H_PTEG_FULL. - + - For the CMO option: CMO Option flags as defined in + For the CMO option: CMO Option flags as defined in . - + For the MUI option: The HBA bits specify settings of implementation dependent PTE bits and associated MUI array entries for the page who’s translation is being entered. - + For the MUI option: The Affinity-Clear and Page-Age-Clear bits clear associated MUI array entries for the page who’s translation is being entered. - + - + PTEX (index of the first PTE in the page table entry group to be used for the PTE insertion) - + PTEH -- the high order 8 bytes of the page table entry. - + PTEL -- the low order 8 bytes of the page table entry. - + Semantics: - + The hypervisor checks that the logical page number is within the bounds of partition allocated memory resources, else returns H_Parameter. - + If the Shared Logical Resource option is implemented and the logical page number represents a page that has been rescinded by the owner, return H_RESCINDED. - + - + The hypervisor checks that the address boundary matches the setting of the input PTE’s large page bits; else return H_Parameter. - + The hypervisor checks that the page size described by the setting of the input PTE’s page size bits is less than or equal to the largest page size supported by the logical region that is being mapped; else return H_Parameter. - + The hypervisor checks that the WIMG bits within the PTE are appropriate for the physical page number else H_Parameter return. (For System Memory pages WIMG=0010, or, 1110 if the SAO option is enabled, and for IO pages WIMG=01**.) - + For pages with sizes greater than 64 K, the hypervisor checks that the Zero Page, I-Cache-Invalidate, and I-Cache_Synchronize bits of the Flags parameter are not set; else return H_TOO_BIG. - + Force off RS mode reserved PTEL bits (1 In addition, bits 52 and 53 are forced off on platforms that - either do not contain an + either do not contain an “ibm,processor-storage-keys” property, - or contain an + or contain an “ibm,processor-storage-keys” property with the value of zero in both cells. Bit 0 is forced off on platforms that do not have the “Support for the “110” value of - the Page Protection (PP) bits” bit set to a value of 1 in the + the Page Protection (PP) bits” bit set to a value of 1 in the “ibm,pa-features” property. ) as well as hypervisor reserved software bits (57 and 58) in PTEH. - + If the Exact flag is off, set the low order 3 bits of the PTEX to zero (insures that the algorithm stays inside partition’s PFT and is faster than a check and error code response). - + If the Zero Page flag is set, use optimized routine to clear page (usually series of dcbz instructions). - + For the PFO option: if the compression flag is on then - + Check that the calling partition is authorized to use the compression co-processor else return H_Function. @@ -6312,67 +6370,67 @@ hcall ( const uint64 H_ENTER, Validate the inlen/in parameters and build the source DDE - + Verify that the “in” parameter represents a valid logical real address within the caller’s partition else return H_P4 - + If the “inlen” parameter is non-negative verify that the logical real address of (in + inlen) is a valid logical real address within the same 4K page as the “in” parameter else return H_P5. - + If the “inlen” parameter is negative: Verify that the absolute value of inlen meet all of the follow else return H_P5: - + - Is <= the value of + Is <= the value of “ibm,max-sg-len” - + Is an even multiple of 16 - + That in + the absolute value of inlen represents a valid logical real address within the same 4K page as the in parameter. - + - + Verify that each 16 byte scatter gather list entry meets all of the following else return H_SG_LIST: - + Verify that the first 8 bytes represents a valid logical real address within the caller’s partition. - + Verify that the logical real address represented by the sum of the first 8 bytes and the second 8 bytes is a valid logical real address within the same 4K page as the first 8 bytes. - + - + Verify that the sum of all the scatter gather length fields (second 8 bytes of each 16 byte entry) is <= the decompression value - in + in “ibm,max-sync-cop” else return H_TOO_BIG. - + @@ -6422,21 +6480,21 @@ hcall ( const uint64 H_ENTER, If hardware error return H_Hardware - + - + If the I-Cache-Invalidate flag is set, issue icbi instructions for all of the page’s cache lines - + If the Cache-Synchronize flag is set, issue dcbst and icbi instructions for all of the page’s cache lines. Implementations may need to issue a sync instruction to complete the coherency management of the I-Cache. - + The hypervisor selects a PTE within the page table entry group using the following. @@ -6462,81 +6520,81 @@ hcall ( const uint64 H_ENTER, If the Page-Age-Clear flag is on clear the MUI PAG for the page; } - + Algorithm: - + if Exact flag is on then set t to 0 else set t to 7 - + for i=0;i<= t; i++ - + Combine page table base, PTEX and offset base on (i) into R3 - + R8 <- ldarx PTEH(R3) /* prepare to take a lock on the PTE */ - + if PTE is valid (R8 (bit 63) is set) then continue - + if PTE is locked (R8 (bit 57) is set) then continue - + set R8 (bit 57) /* prepare to lock PTE */ - + PTEH(R3) <- stdcx R8 /* attempt to take lock */ - + if stdcx failed continue - + goto insert - + - + return H_PTEG_FULL - + insert: use code sequence from PA Book III - + construct return PTEX (R4 <- (R3 - PFTbase) shifted down 4 places) - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + return H_Success - +
@@ -6550,101 +6608,101 @@ hcall ( const uint64 H_ENTER, Syntax: - + Parameters: - + flags: - + CEC Cookie: Cross CEC PFT access - + READ_4: Return 4 PTEs - + R-XLATE: Include a valid logical page number in the PTE if the valid bit is set, else the contents of the logical page number field is undefined. - + - For the CMO option: CMO Option flags as defined in + For the CMO option: CMO Option flags as defined in . - + - + PTEX (index of the PTE in the page table to be used -- if the READ_4 flag is set the low order two bits of the PTEX are forced to zero by the hypervisor to insure that they are in the range of the PTEG and it is faster than checking.) - + - + Semantics: - + Checks that the PTEX is within the defined range of the partition’s PFT else return H_Parmaeter - + If the READ_4 bit is clear Then load the specified PTE into R4 and R5 - + If R-XLATE flag is set, then reverse translate the RPN field into the logical page number. - + - + Else - + clear the two low order bits of the PTEX (faster than checking them) - + load the 4 PTEs starting at PTEX into R4 through R11. - + If R-XLATE flag is set, then reverse translate the RPN fields into the logical page number. - + - + - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + Set H_Success in R3 and return - +
@@ -6664,92 +6722,92 @@ hcall ( const uint64 H_CLEAR_MOD, /* Clears the PTE Modified bit */ uint64 flags, /* None Defined */ int64 PTEX ); /* Index of the PTE to be used */]]> - + Parameters: - + - flags: For the CMO option: CMO Option flags as defined in + flags: For the CMO option: CMO Option flags as defined in . - + PTEX (index of the PTE in the page table to be used) - + - + Semantics: - + Check that the PTEX accesses within the PFT, else returns H_Parameter - + Check that the “V” bit is one, else return H_Not_Found. - + Fetch the low order double word of the PTE into R4. If the “C” bit is zero, then return H_Success. - + The hypervisor synchronizes the PTE specified by the PTEX, clears the mod bit, and returns its old value: - + Use the architected “Modifying a Page Table Entry General Case” sequence from PA Book III. - + Only PTE bits to be modified are: - + In double word 0 SW bit 57 and the V bit (63) - + In double word 1, C bit (56). - + - + Use the proper tlbie instruction for the page size (per large page flag within PTE) within a critical section protected by the proper lock. - + The second double word of the old PTE value ends up in R4. - + At the point where the new values are to be activated, use the old values with the “C” bit cleared. - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + Return H_Success - + - +
@@ -6768,62 +6826,62 @@ hcall ( const uint64 H_CLEAR_REF, /* Clears the PTE Reference bit */ uint64 flags, /* None Defined */ int64 PTEX ); /* index of the PTE to be used */]]> - + Parameters: - + - flags: For the CMO option: CMO Option flags as defined in + flags: For the CMO option: CMO Option flags as defined in . - + PTEX (index of the PTE in the page table to be used) - + - + Semantics: - + Check that the PTEX accesses within the PFT, else return H_Parameter. - + Check that the “V” bit is one, else return H_Not_Found. - + Only PTE bits to be modified are: - + In double word 1 the R bit (55) - + - + Use the architected “Resetting the Reference Bit” sequence from PA Book III with the original second double word of the PTE ending up in R4. - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + Return H_Success - +
@@ -6842,121 +6900,121 @@ hcall ( const uint64 H_PROTECT, /* Changes the page protection specification */ int64 PTEX, /* index of the PTE to be used */ uint64 AVPN ); /* Abbreviated virtual page number */]]> - + Parameters: - - + + flags: AVPN, pp0 The pp0 portion of the flags parameter is ignored on platforms that do not have the “Support for the “110” value of - the Page Protection (PP) bits” bit set to a value of 1 in the + the Page Protection (PP) bits” bit set to a value of 1 in the “ibm,pa-features” property. , pp1, pp2, key0-key4 The key0-key4 portion of the flags parameter is ignored on - platforms that either do not contain an + platforms that either do not contain an “ibm,processor-storage-keys” property, - or contain an + or contain an “ibm,processor-storage-keys” property with the value of zero in both cells. - , n, and for the CMO option: CMO Option flags as defined in + , n, and for the CMO option: CMO Option flags as defined in . - + PTEX (index of the PTE in the page table to be used) - + AVPN: Optional “Abbreviated Virtual Page Number” -- used as a check for the correct PTE when the AVPN flag is set. - + - + Semantics: - + Check that the PTEX accesses within the PFT, else return H_Parameter - + Check that the “V” bit is one, else return H_Not_Found. - + If the AVPN flag is set, and the AVPN parameter bits 0-56 do not match that of the specified PTE, then return H_Not_Found. - + The hypervisor synchronizes the PTE specified by the PTEX, sets the pp0 The pp0 bit is not modified on platforms that do not have the “Support for the “110” value of the Page Protection - (PP) bits” bit set to a value of 1 in the + (PP) bits” bit set to a value of 1 in the “ibm,pa-features” property. , pp1, pp2, key0-key4 The key0 - key4 bits are not modified on platforms that either - do not contain an “ibm,processor-storage-keys” - property, or contain an + do not contain an “ibm,processor-storage-keys” + property, or contain an “ibm,processor-storage-keys” property with the value of zero in both cells. , and n bits per the flags parameter. - + Only PTE bits to be modified are: - + In double word 0 SW bit 57 and the V bit (63) - + - In double word 1 pp0, pp1, pp2, + In double word 1 pp0, pp1, pp2, key0-key4, and n - + - + Use the architected “Modifying a Page Table Entry General Case” sequence. - + Use the proper tlbie instruction for the page size (per value in PTE) within a critical section protected by the proper lock. - + At the point where the new values are to be activated use the old - values with the “R” bit cleared and the - pp0, + values with the “R” bit cleared and the + pp0, pp1, pp2, key0-key4, and n bits set as specified in the flags parameter. - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + Return H_Success - + - +
@@ -6988,145 +7046,145 @@ hcall ( const int64 H_BULK_REMOVE, /* Function Code */ Each is 16 bytes long made up of two 8 byte double words; a translation specifier high and a translation specifier low. - + Translation Specifier High double word: - + First byte (0) is a control/status byte: - + High order two bits (0 and 1) are type code: - + 00 Unused -- if found stop processing and return H_PARAMETER - + 01 Request -- Processes As per H_REMOVE as modified by low order two control bits. - + 10 Response -- written by hypervisor as a return status from processing individual “request” translation specifier - + 11 End of String -- if found stop processing and return H_Success. - + - + Next two bits (2 and 3) are response code (in response to processing an individual “request” translation specifier (type code modified to 10)): - + 00 Success -- the specified translation was removed as per H_REMOVE with the PTE's RC bits in the next two status bits. - + 01 Not found -- the specified translation was not found as per H_REMOVE. - + 10 H_PARM -- one or more of the parameters of the specified translation were invalid per H_REMOVE -- processing of the bulk entries stops at this point and the hypervisor returns H_PARAMETER. - + 11 H_HW -- The hardware experienced an uncorrected error processing this translation specifier -- processing of the bulk entries stops at this point and the hypervisor returns H_HARDWARE. - + - + Next two bits (4 and 5) are the Reference/Change bits from the removed PTE (These bits are only valid if bits 0-3 are 1000): - + Low order two bits (6 and 7) are request modification flags: - + 00 absolute -- remove the specified PTEX entry unconditionally - + 01 andcond -- remove the specified PTEX entry as with the andcond flag of H_REMOVE - + 10 AVPN -- remove the specified PTEX entry as with the AVPN flag of H_REMOVE - + 11 not used -- if found stop processing and return H_PARAMETER. - + - + - + Bytes 1 through 7 are the PTEX (PFT byte offset divided by 16) - + - + Translation Specifier Low double word: - + Bytes 0 through 7 are the AVPN as per H_REMOVE - + - + - + Semantics: - + For each translation specifier, while the translation specifier is not “end of string”: - + Check that the PTEX accesses within the PFT else set H_PARM response status in the specific translation specifier high register and return H_Parameter - + If the AVPN flag is set, and the AVPN parameter bits 0-56 do not match that of the specified PTE then set response status Not found in the specific translation specifier high register, Continue. - + If the andcond flag is set, the AVPN parameter is bit anded with the first double word of the specified PTE (after bits 57-63 of the PTE @@ -7135,56 +7193,56 @@ hcall ( const int64 H_BULK_REMOVE, /* Function Code */ (Note the low order 7 bits of the AVPN parameter should be zero otherwise the likely result is a response status of Not found). - + The hypervisor Synchronizes the PTE specified by the PTEX. - + Use the architected “Deleting a Page Table Entry” sequence. - + Use the proper tlbie instruction for the page size within a critical section protected by the proper lock (per large page bit in the specified PTE). - + The synchronized value of the old PTE RC bits ends up in bits 4 and 5 of the individual translation specifier high register along with success response status. - + - + return H_Success - +
H_BLOCK_REMOVE - - This hcall removes up to eight sequential virtual + + This hcall removes up to eight sequential virtual page table entries. Some platforms that support this hcall() might remove - fewer than 8 entries for a given actual page size / base page + fewer than 8 entries for a given actual page size / base page size combination as communicated by the “Block Invalidate - Characteristics” system parameter (see + Characteristics” system parameter (see ). - The virtual pages are all within + The virtual pages are all within the same naturally aligned 8 page virtual address block and - have the same page and segment size encodings. The AVA parameter, + have the same page and segment size encodings. The AVA parameter, if used, covers the entire block of virtual page - addresses. If another processor is currently accessing + addresses. If another processor is currently accessing the page table entry, the entry is not removed. The availability of - is hcall() might change after partition migration, the + is hcall() might change after partition migration, the caller should be prepared for an H_Function return code. The - PTEX field of the translation specifier parameters + PTEX field of the translation specifier parameters identifies the specific page table entries. @@ -7205,9 +7263,9 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ uint64 TS7 ); /* Translation Specifier Seven */]]> The AVA parameter is the 8 byte AVPN as per H_REMOVE. - + Each Translation Specifier is 8 bytes long: - + H_BLOCK_REMOVE Translation Specifier @@ -7474,7 +7532,7 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ 0 0 0 - Success -- the specified translation was removed as per H_REMOVE + Success -- the specified translation was removed as per H_REMOVE with the PTE's RC bits in the next two status bits. @@ -7494,7 +7552,7 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ 0 1 1 - Inconsistent Page/Segment Size (does not match the L||LP and B + Inconsistent Page/Segment Size (does not match the L||LP and B fields of the block anchor Page Table Entry) @@ -7519,7 +7577,7 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ 1 1 1 - The hardware experienced an uncorrected error processing this translation specifier -- + The hardware experienced an uncorrected error processing this translation specifier -- processing of the bulk entries stops at this point and the hypervisor returns H_HARDWARE. @@ -7543,11 +7601,11 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */
- + Semantics: - + Initialize return code to H_Success (overwritten if appropriate) @@ -7556,7 +7614,7 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ For each translation specifier, while the translation specifier type is not “end of string”: - + If the translation specifer type is not “Request” Return H_PARAMETER. @@ -7586,11 +7644,11 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ If NOT Anchored: - + then: - + Establish the block L||LP @@ -7676,16 +7734,270 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */
+
+ Hash Page Table Resize Option + + The hash page table (HPT) for an operating system needs to be + sized depending on the size of the partition's memory. The usual rule of + thumb is that the HPT should be 1/64th of the size of memory (although + Linux will typically work well with 1/128th or even less depending on + available page sizes). An HPT which is too small will lead to poor performance, + or even crashes, if the OS is unable to fit necessary bolted mappings into + the table. An HPT which is too large wastes memory and leads to slower + TLB misses due to increased cache misses on table walks. + + With the size of the HPT fixed at boot, a partition allowing memory + reconfiguration must size the HPT according to the partition's maximum + possible memory size. If the partition has a very large potential maximum + memory size, but is un- likely to reach that in practice, this can lead to + significant wastage of resources in the oversized hash table. By allowing + a partition to change its HPT size at runtime, it can start with an HPT + sized just for its initial memory, and change it if necessary when more + memory is added dynamically. + + If the platform supports the Hash Page Table Resize Option, then it supports + the two hcalls defined in this section, which allow an OS to request that its + HPT should be resized. The resize operation is performed in two phases, the + “pre- pare” phase and the “commit” phase. The prepare phase may take place + concurrently with normal guest operation. The commit phase requires that the + guest perform no concurrent updates or accesses to the HPT (which in practice + requires no non-real mode memory accesses). + + + During operation a partition may have a “Pending HPT”, a block of platform + memory organized as a Power hash page table which may become the partition's + HPT in future. The following data are associated with a Pending HPT: + + + Does a Pending HPT currently exist? + + + The Pending HPT's size + + + Flags associated with the Pending HPT (this is for future + extension, no flags are currently defined) + + + Whether the Pending HPT is fully prepared or not + + + + + In order to prevent a partition from tying up platform resources + indefinitely with a Pending HPT, the platform is per- mitted to discard a + Pending HPT at any time. Operating systems should be prepared to deal + with a failure of either hcall because of this. + + The platform is permitted to start a partition with its HPT sized + for the current memory allocation, rather than the max- imum memory for + the partition, provided that if the OS indicates via the + ibm,client-architecture-support call that it does not support HPT resizing, + the platform must then resize the HPT according to the partition's maximum + memory, using a reconfiguration reboot if necessary. + +
+ H_RESIZE_HPT_PREPARE + + This hcall controls the prepare phase of HPT resizing. After + successful completion of this hcall, the partition has a Pending + HPT which can be made the partition's current HPT. + + + Syntax: + + + + + + Parameters: + + + + flags: 0, as no flags are currently defined. + + + shift: Log base 2 of the total size in bytes of the + requested new HPT, either 0 (used to discard a Pending HPT) + or else between 18 and 46. + + + + + + Semantics: + + + + Check that the partition is permitted to resize its HPT, else + return H_AUTHORITY. + + + Check if there is a Pending HPT; if there is, then: + + + If the Pending HPT size and flags match the parameters requested in this call, then: + + + If the Pending HPT is not fully prepared, return + H_LONG_BUSY_xxx with an estimate of the time remaining + to complete preparation of the Pending HPT + + + If preparation of the Pending HPT has terminated + due to two bolted HPTEs needing to occupy the same + slot of the same HPTEG, then return H_PTEG_FULL + + + Else return H_SUCCESS + + + + + + Else discard the Pending HPT and continue + + + + + + If the flags parameter is non-zero, then return H_PARAMETER + + + If shift is zero, then return H_SUCCESS + + + If (shift < 18) or (shift > 46), then return H_PARAMETER + + + Check that the partition is permitted to have an HPT of 2shift + bytes; if not, return H_RESOURCE + + + Create a new Pending HPT of size 2shift bytes. Preparation of + the new HPT may continue asynchronously. + + + If the Pending HPT is not fully prepared, return + H_LONG_BUSY_xxx with an estimate of the time remaining to + complete preparation. + + + Else return H_SUCCESS. + + + +
+ +
+ H_RESIZE_HPT_COMMIT + + This hcall executes the commit phase of HPT resizing, making the + Pending HPT the partition's current HPT. The caller must ensure that + while it is executing, none of the partition's virtual CPU threads + will update or access the HPT; that is, all threads must be executing + in real mode, or stopped. + + + Syntax: + + + + + + Parameters: + + + + flags: 0, as no flags are currently defined. + + + shift: Log base 2 of the total size in bytes of the + requested new HPT, between 18 and 46. + + + + + + Semantics: + + + + Check that the partition is permitted to resize its HPT, + else return H_AUTHORITY. + + + Check if there is a Pending HPT; if there is not, then + return H_CLOSED. + + + Check that the flags parameter is zero and the shift + parameter matches the size of the Pending HPT; if not, then + re- turn H_CLOSED. + + + Check that the Pending HPT is fully prepared; if not, + return H_BUSY. + + + If preparation of the Pending HPT was terminated due to finding + two bolted HPTEs that need to occupy the same + slot of the same HPTEG, then return H_PTEG_FULL. + + + Ensure that all bolted HPTEs from the partition's existing HPT + also exist, correctly hashed, in the Pending HPT. HPTEs transferred + from the existing HPT must have the same slot within their HPTEG in + the Pending HPT as they did in the existing HPT. If the Pending HPT + is smaller than the existing HPT, it is possible that two bolted HPTEs + that are in the same slot of two separate HPTEGs in the existing HPT + need to be put into the same HPTEG in the Pending HPT. If this occurs, + return H_PTEG_FULL. + + + Discard the partition's existing HPT. + + + Make the Pending HPT be the partition's current HPT. + + + Mark the partition as having no Pending HPT. + + + Return H_Success. + + + +
+
+
Translation Control Entry Access The Translation Control Entry (TCE) access hcall()s take as a parameters the Logical I/O Bus Number (LIOBN) that is the logical bus - number value derived from the + number value derived from the “ibm,dma-window” property associated with - the particular IOA. For the format of the - “ibm,dma-window” property, reference + the particular IOA. For the format of the + “ibm,dma-window” property, reference .
@@ -7709,69 +8021,69 @@ hcall ( const uint64 H_GET_TCE, /* Return the contents of the specified TCE */ uint64 IOBA ); /* I/O Bus Address for indexing into the TCE table */]]> - + Parameters: - + LIOBN (Logical I/O Bus Number for TCE table to be accessed) - + IOBA (I/O Bus Address for indexing into the TCE table) - + - + Semantics: - + If the LIOBN, or IOBA are outside of the range of calling partition assigned values return H_PARAMETER. - + If the Shared Logical Resource option is implemented and the LIOBN, or IOBA represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + Load R4 with the specified TCE contents. - + - If specified TCE’s Page Mapping and Control bits (see + If specified TCE’s Page Mapping and Control bits (see ) specify “Page Fault” then return H_Success - + Reverse translate the TCE’s RPN field into its logical page number - + If the logical page number is owned by the calling partition then replace the RPN field of R4 with the logical page number and return H_Success. - + Logically OR the contents of R4 with 0xFFFFFFFFFFFFF000 placing the result into R4. - + Return H_PARTIAL. - +
@@ -7800,35 +8112,35 @@ hcall ( const uint64 H_PUT_TCE, /* Function Token */ );]]> - + Semantics: - + If the LIOBN or IOBA parameters are outside of the range of calling partition assigned values return H_PARAMETER. - + If the Shared Logical Resource option is implemented and the LIOBN, or IOBA represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + If the Page Mapping and Control field of the TCE is not - “Page Fault” (see + “Page Fault” (see ) - + Then if the logical address within the TCE parameter is outside of the range of calling partition assigned values - + Then return H_PARAMETER. @@ -7837,11 +8149,11 @@ hcall ( const uint64 H_PUT_TCE, /* Function Token */ Else translate the logical address within the TCE parameter into the corresponding physical real address. - + - + - + The hypervisor stores the TCE resultant value in the TCE table specified by the LIOBN and IOBA parameters; returning H_Success. (In the @@ -7854,7 +8166,7 @@ hcall ( const uint64 H_PUT_TCE, /* Function Token */ visibility of TCE data and in no way diminishes the requirement for the OS to issue it. - +
@@ -7888,74 +8200,74 @@ hcall ( const uint64 H_STUFF_TCE, /* Function Token */ uint64 count );/* The number of consecutive TCEs to fill */]]> - + Semantics: - + If the LIOBN, or IOBA, are outside of the range of calling partition assigned values return H_PARAMETER. - + If the Shared Logical Resource option is implemented and the LIOBN, or IOBA represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + If the count parameter is greater than 512 then return H_P4 - + If the count parameter added to the TCE index specified by IOBA is outside of the range of the calling partition assigned values return H_PARAMETER. - + If the Page Mapping and Control field of the TCE is not - “Page Fault” (see + “Page Fault” (see ) - + Then if the logical address within the TCE parameter is outside of the range of calling partition assigned values - + Then return H_PARAMETER. - + If the Shared Logical Resource option is implemented and the logical address’s page number represents a page that has been rescinded by the owner, return H_RESCINDED. - + - + Else translate the logical address within the TCE parameter into the corresponding physical real address. - + - + - + The hypervisor stores the TCE resultant value in the TCE table entries specified by the LIOBN, IOBA and count parameters; returning H_Success. (In the “Page Fault” case the RPN remains untranslated.) - + Implementation Note: The PA requires the OS to issue a sync instruction to proceed the signaling of an IOA to start an IO operation @@ -8008,252 +8320,252 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ Semantics: /* Validate the input parameters */ - + If the LIOBN parameter is non-negative then do - + If the count parameter is > 512 then return H_Parameter. - + If the Shared Logical Resource option is implemented and the LIOBN parameter represents a TCE table that has been rescinded by the owner, return H_RESCINDED. - + If the LIOBN parameter represents a TCE table that is not valid for the calling partition, return H_Parameter. - + Liobns[0] = the LIOBN parameter. - + If the Shared Logical Resource option is implemented and any of the I/O bus address range represented the IOBA parameter plus count pages within the TCE table represented by the LIOBN parameter represents rescinded resource, return H_RESCINDED. - + If any of the I/O bus address range represented the IOBA parameter plus count pages within the TCE table represented by the LIOBN parameter is not valid for the calling partition then return H_Parameter. - + end - + - + Else do - + If the MTT Option is not enabled return H_Function. - + If the LIOBN parameter < -128 then return H_Parameter. - + If the sum of the count parameter plus |LIOBN| is > 512 then return H_Parameter. - + end - + - + If the Shared Logical Resource option is implemented and the TCE parameter represents a logical page address of a page that has been rescinded by the owner, return H_RESCINDED. - + If the TCE parameter represents the logical page address of a page that is not valid for the calling partition, return H_Parameter. - + Copy the contents of the page referenced by the TCE table to a temporary hypervisor page (Temp) for validation without the potential for caller manipulation. - + /* Validate the indirect parameters */ - + VAL= 0 - + If the LIOBN parameter is negative then do - + For CNT = 1,|LIOBN|,1 - + T = 8 byte entry Temp [VAL] - + If the Shared Logical Resource option is implemented and T as an LIOBN represents a TCE table that has been rescinded by the owner, return H_RESCINDED. - + If T as an LIOBN represents a TCE table that is not valid for the calling partition, return H_Parameter. - + Liobns[VAL+] = T. - + If the Shared Logical Resource option is implemented and any of the I/O bus address range represented the IOBA parameter plus count pages within the TCE table represented by “T” as an LIOBN represents a rescinded resource, return H_RESCINDED. - + If any of the I/O bus address range represented the IOBA parameter plus count pages within the TCE table represented by “T” as an LIOBN is not valid for the calling partition then return H_Parameter. - + loop - + end - + - + /* Translate the logical pages addresses to physical*/ - + for CNT = 1,count,1 - + T = 8 byte entry Temp [VAL+] - + If the Page Mapping and Control field of the 8 byte entry - “T” is not “Page Fault” (see + “T” is not “Page Fault” (see ) then do - + If the Shared Logical Resource option is implemented and the value of “T” as a logical address represents a page that has been rescinded by the owner, then return H_RESCINDED. - + If “T” as a logical address is outside of the range of calling partition assigned values then return H_PARAMETER. - + Translate the logical address within the TCE buffer entry into the corresponding physical real address. - + Temp[CNT - 1] = translated physical real address. - + end - + - + loop - + - + /* Fill the TCE table(s) */ - + If LIOBN parameter is negative then VAL = |LIOBN| else VAL = 1. - + For TABS = 1, VAL, 1 - + The TCE table to fill is that referenced by Liobns[VAL] as an LIOBN. - + INDEX = the page index within the TCE table represented by the IOBA parameter. - + For CNT = 1, count, 1 - + TCE_TABLE [Liobns[VAL], INDEX+] = Temp [CNT-1] - + Loop - + - + Loop - + - + Return H_Success. @@ -8269,13 +8581,13 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */
- +
Processor Register Hypervisor Resource Access Certain processor registers are architecturally hypervisor resources, in the following cases the hypervisor provides controlled write access services. - +
H_SET_SPRG0 @@ -8286,7 +8598,7 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ Parameters: - + value: The value to be written into SPRG0. No parameter checking @@ -8300,7 +8612,7 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ H_SET_DABR Note: Implementations reporting compatibility to ISA versions less than 2.07 are required to implement this interface; however, this - interface is being deprecated in favor of + interface is being deprecated in favor of for newer implementations. @@ -8308,139 +8620,139 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ Syntax: - + Semantics: - + If the platform does not implement the extended DABR facility then: - + Validate the value parameter else return H_RESERVED_DABR and the value in the DABR is not changed: - + The DABR BT bit (Breakpoint Translation) is checked for a value of 1. - + - + - + Else (The platform does implement the extended DABR facility): - + Load the DABRX register with 0b0011. - + place the value parameter into the DABR. - + Return H_Success. - +
- +
H_PAGE_INIT Syntax: - Parameters: - + flags: zero, copy, I-Cache-Invalidate, I-Cache-Synchronize, and - for the CMO option: CMO Option flags as defined in + for the CMO option: CMO Option flags as defined in . - + destination: The logical address of the start of the page to be initialized - + source: The logical address of the start of the page use as the source on a page copy initialization. This parameter is only checked and used if the copy flag is set. - + - + Semantics: - + The logical addresses are checked, they must both point to the start of a 4 K system memory page associated with the partition or return H_Parameter. - + If the Shared Logical Resource option is implemented and the source/destination logical page number represents a page that has been rescinded by the owner, return H_RESCINDED. - + - + If the zero flag is set, clear the destination page using a platform specific routine (usually a series of dcbz instructions). - + If the copy flag is set, execute a platform specific optimized copy of the full 4 K page from the source to the destination. - + If I-Cache-Invalidate flag is set, issue icbi instructions for all of the page’s cache lines - + If I-Cache-Synchronize flag is set, issue dcbst and icbi instructions for all of the page’s cache lines. Implementations may need to issue a sync instruction to complete the coherency management of the I-Cache. - + For the CMO option: set the page usage state per the CMO Option - flags field of the flags parameter as defined in + flags field of the flags parameter as defined in . - + Return H_Success - + Note: For the CMO option, the CMO option flags may be used to notify the platform of the page usage state of a page without @@ -8453,7 +8765,7 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ H_SET_XDABR Note: Implementations reporting compatibility to ISA versions less than 2.07 are required to implement this interface; however, this - interface is being deprecated in favor of + interface is being deprecated in favor of for newer implementations. This hcall() provides support for the extended Data Address @@ -8479,28 +8791,28 @@ hcall ( const uint64 H_SET_XDABR, /* Function Token */ Validates the extended parameter else return H_Parameter: - + Reserved Bits (0-59) are zero. - + The HYP bit (61) is off. - + The rest of the PRIVM field (Bits 62-63) is one of those supported: - + 0b01 Problem State - + 0b10 Privileged non-hypervisor - + 0b11 Privileged or Problem State @@ -8511,7 +8823,7 @@ hcall ( const uint64 H_SET_XDABR, /* Function Token */ - + Load the validated extended parameter into the DABRX @@ -8525,20 +8837,20 @@ hcall ( const uint64 H_SET_XDABR, /* Function Token */
- +
H_SET_MODE This hcall() is used to set hypervisor processing resource mode registers such as breakpoints and watchpoints. The modes supported by the hardware processor are a function of the processor architectural level as - reported in the - “cpu-version” property. + reported in the + “cpu-version” property. presents the valid parameter - ranges for the architectural level reported in the + ranges for the architectural level reported in the “cpu-version” property - and the LoPAR architecture level as reported in the + and the LoPAR architecture level as reported in the “/chosen” property. - + Setting breakpoints: A breakpoint is set for a hardware tread. Should the hardware thread complete an instruction who's effective address matches that of the set breakpoint a trace interrupt is signaled. @@ -8567,11 +8879,11 @@ hcall ( const uint64 H_SET_XDABR, /* Function Token */ mode setting. The desired AIL mode is encoded in the two low order mflags bits (all other mflags bits are 0) while both value1 and value2 parameters are zero. - - The POWER ISA requires that the setting the LPCR ILE bit be the same - in all partition processors when not in hypervisor mode thus all partition - processors need to be operating with MSR[EE] = 0 when changing LPCR ILE so - that the OS can change the contents of the interrupt vectors prior to any + + The POWER ISA requires that the setting the LPCR ILE bit be the same + in all partition processors when not in hypervisor mode thus all partition + processors need to be operating with MSR[EE] = 0 when changing LPCR ILE so + that the OS can change the contents of the interrupt vectors prior to any interrupts being taken in the new mode. @@ -8599,7 +8911,7 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ case 1: /* Completed Instruction Address Breakpoint Register */ if value2 <> 0 the return H_P4; if mflags <> 0 then return H_UNSUPPORTED_FLAG; - If low order two bits of value1 are 0b11 then return H_P3; /* not hypervisor + If low order two bits of value1 are 0b11 then return H_P3; /* not hypervisor instruction address */ move value 1 into CIABR; /* note the value2 parameter is not used for this resource */ break; @@ -8625,7 +8937,7 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ case 3: / * IR = DR = 1 interrupt vectors at E.A. 0XC000 0000 0000 4000 * / Set LPCR AIL field of calling partition processors to 0b11; break; - default: + default: return H_UNSUPPORTED_FLAG (value based on most convenient unsupported bit); break; /* Starting with PAPR Version 2.8 add the following */ @@ -8647,7 +8959,7 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ Else On each partition processor set LPCR[ILE] = 1 return H_Success; - default: + default: return H_UNSUPPORTED_FLAG (value based on most convenient unsupported bit); break; default: @@ -8835,12 +9147,12 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ - R1-R1--1. For implementations supporting POWER ISA level 2.07 and beyond: the platform must implement the H_SET_MODE - hcall() per the syntax and semantics of section + hcall() per the syntax and semantics of section per the LoPAR level supported. @@ -8851,7 +9163,7 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
Implementation Dependent Optimizations - + All platforms contain implementation specific switches and values that effect the performance of the platform. The default settings for switches and values are tuned during platform development to achieve the desired performance characteristics across a wide range of workloads. However, the performance of specific workloads might be further @@ -8861,21 +9173,21 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ 2.8 and above provide the hcall()s defined below to set a subset of the implementaion specific switches and adjust a subset of the tuning values within a range that has been proven to be safe. The caller is expected to understand the switch banks and resources implemented by the specific platform and the functinality of each individual switch and resource. - + Special consideration is required of the caller of these functions during partition migration and micro-checkpoint/ failover operations since the underlying implementation might change. During these operarations, the implementation dependent switches and values are set to their default values for the implementation that is receiving the partition. After a migration or failover event the availability of the Implementation Dependent Optimization hcall()s might change, along with the resources and/or switch banks that might be adjusted, and the supported values for those adjustments. - +
H_ADJUST_RESOURCE - + This hcall() is used to adjust the value of a given implementation dependent resource in contiguous unit steps between the minimum and maximum supported values. These steps are not necessarily uniform either in physical values set into the implementation dependent resource or the resultant effect they have on workload performance. - + Syntax: - + Semantics: @@ -8904,11 +9216,11 @@ hcall ( const uint64 H_ADJUST_RESOURCE, /* Function Code */ If the value of the Resource parameter is zero then return H_PARAMETER - If the value of the Resource parameter is greater than the maximum defined + If the value of the Resource parameter is greater than the maximum defined value then return H_RESERVED - If the value of the Resource paramter is not supported on this implementation + If the value of the Resource paramter is not supported on this implementation then return H_UNSUPPORTED @@ -8962,13 +9274,13 @@ hcall ( const uint64 H_ADJUST_RESOURCE, /* Function Code */
- +
H_SET_SWITCHES - + This hcall() provides for the setting of an implementation dependent subset of the switches in an implementation dependent bank of switches. - + Syntax: If the value of the Bank parameter is zero then return H_PARAMETER - If the value of the Bank parameter is greater than the maximum defined + If the value of the Bank parameter is greater than the maximum defined value then return H_RESERVED - If the value of the Bank paramter is not supported on this implementation + If the value of the Bank paramter is not supported on this implementation then return H_UNSUPPORTED - If (Mask & not (Supported-bits-in[Bank]) ) then RC = H_Constrained + If (Mask & not (Supported-bits-in[Bank]) ) then RC = H_Constrained else RC = H_Success - Turn on the bits in switches[Bank] that are ones in all three of + Turn on the bits in switches[Bank] that are ones in all three of Supported-bits-in[Bank], Mask, and Setting - Turn off the bits in switches[Bank] that are ones in both + Turn off the bits in switches[Bank] that are ones in both Supported-bits-in[Bank] and Mask but are zeros in Setting @@ -9052,37 +9364,37 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ Syntax: - + Parameters: - + size: The size of the cache inhibited load: - + byte = 1 - + half = 2 - + full = 4 - + double=8 - + All other size values are illegal and returns H_Parameter - + - + addr: The logical address of the cache inhibited location to be read. The hypervisor checks that the address is within the range of @@ -9091,12 +9403,12 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ and mapped as cache inhibited (cache paradoxes are to be avoided)-- Else H_Parameter. - + On successful return (H_Success), the read value is low order justified in register R4. - +
@@ -9106,42 +9418,42 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ Syntax: - Parameters: - + size: The size of the cache inhibited store: - + byte = 1 - + half = 2 - + full = 4 - + double=8 - + All other size values are illegal and returns H_Parameter - + - + addr: The logical address of the cache inhibited location to be written. The hypervisor checks that the address is within the range of @@ -9149,12 +9461,12 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ length, is not to the location BA+4 within an interrupt management area, and mapped as cache inhibited (cache paradoxes are to be avoided). - + value The value to be written is low order justified in register R6. - +
@@ -9162,19 +9474,19 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */
Virtual Terminal Support - This section has been moved to + This section has been moved to . Architecture and Implementation Note: The requirement - to provide the - “ibm,termno” property in the + to provide the + “ibm,termno” property in the /rtas node, has been removed (it is now necessary to - look for - vty nodes and use their unit address from the + look for + vty nodes and use their unit address from the “reg” property to get the same - information). The + information). The “ibm,termno” property called for - sequential terminal numbers, but with the use of unit addresses from the + sequential terminal numbers, but with the use of unit addresses from the “reg” property, such is not the case.
@@ -9187,7 +9499,7 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ disabled) via the Hardware Management Console. If the hcall-dump function set is disabled an attempt to make a H_HYPERVISOR_DATA hcall() returns H_Function. When the function is enabled, the hcall-dump function set is - specified in the + specified in the “ibm,hypertas-functions” property. The requester calls repeatedly starting with a control value of zero getting back 64 bytes per call and setting the control parameter on the next call @@ -9197,8 +9509,8 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ H_HYPERVISOR_DATA hcall() need only return data in the firmware working storage that is not contained in the PFT or TCE tables since the contents of these tables are available to the OS. - - Starting with LoPAR Version 2.8 PAPR platforms support the + + Starting with LoPAR Version 2.8 PAPR platforms support the H_CLEAR_HPT hcall() independent of Client Architecture support negotiation.
@@ -9212,24 +9524,24 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ Parameters: - + control: A value passed to establish the progress of the dump. - + Semantics: - + If the control value is zero, the data returned is the first segment of the hypervisor’s working storage, with a non-negative return code. - + If the control value is equal to the return code of the last H_HYPERVISOR_DATA call, and the return code is non-negative, the data @@ -9237,7 +9549,7 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */ hypervisor’s working storage. The contents of R4 through R11 are undefined if the return code is negative. - + Implementation Note: It is expected that the control value is be used by the H_HYPERVISOR_DATA routine as an offset into the @@ -9250,7 +9562,7 @@ hcall ( const uint64 H_SET_SWITCHES, /* Function Code */
H_CLEAR_HPT - + This hcall() clears the hash page table (HPT) for a partition in preparation for a restart. The Virtual Real Mode Area and Partition Adjunct mappings are exempted. The performance class of this hcall() is “Terminal”, that is, it is allowed to take as long as it needs to perform the operation in a single call, @@ -9280,15 +9592,15 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Semantics: - + Disable other HPT access hcall()s - + For each HPT entry - - + + If the entry does not map the VRMA or Partition Adjunct clear the V bit @@ -9298,15 +9610,15 @@ hcall ( const uint64 H_CLEAR_HPT);]]> For each partition processor perform a TLBIA - + Enable other HPT access hcall()s - + Return H_Success - +
@@ -9316,7 +9628,7 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Injudicious values written to the interrupt source controller may affect innocent partitions. The following hcall()s monitor the architected functions. - +
H_EOI @@ -9333,26 +9645,26 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Parameters: - + xirr: The low order 32 bits is the value to be written into the calling processor’s interrupt management area’s external interrupt request register (xirr). - + - + Semantics: - + If the platform implements the Platform Reserved Interrupt Priority Level Option, and the priority field of the xirr parameter matches one of the reserved interrupt priorities then return H_Resource. - + If the value of the xirr parameter is such that the low order 3 bytes (xisr) is one of the interrupt source values assigned to the @@ -9364,20 +9676,20 @@ hcall ( const uint64 H_CLEAR_HPT);]]> H_Hardware (if an unrecoverable hardware error occurred). If the xirr value is not legal, hypervisor returns H_Parameter. - + If the Shared Logical Resource option is implemented and the xirr parameter represents a shared logical resource location that has been rescinded by the owner, return H_RESCINDED. - + If the partition is not in XIVE legacy mode, the Hypervisor returns H_Function. - +
@@ -9392,26 +9704,26 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Parameters: - + cppr: The low order byte is the value to be written into the calling processor’s interrupt management area’s current processor priority register (cppr). - + - + Semantics: - + If the platform implements the Platform Reserved Interrupt Priority Level Option, and the priority field of the xirr parameter matches one of the reserved interrupt priorities then return H_Resource. - + The value of the cppr parameter is written into the calling processor’s cppr causing the interrupt source controller to reject @@ -9425,7 +9737,7 @@ hcall ( const uint64 H_CLEAR_HPT);]]> H_Function. - +
@@ -9440,32 +9752,32 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Parameters: - + - server#: The server number gotten from the + server#: The server number gotten from the “ibm,ppc-interrupt-server#s” property associated with the processor and/or thread to be interrupted. - + mfrr: The priority value the inter-processor interrupt to be signaled. - + - + Semantics: - + If the platform implements the Platform Reserved Interrupt Priority Level Option, and the priority field of the xirr parameter matches one of the reserved interrupt priorities then return H_Resource. - + If the value of the server# parameter specifies of one of the processors in the calling processor’s partition, then the value in @@ -9477,13 +9789,13 @@ hcall ( const uint64 H_CLEAR_HPT);]]> H_Success or H_Hardware (if an unrecoverable hardware error occurred). If the server# value is not legal, hypervisor returns H_Parameter. - + If the Shared Logical Resource option is implemented and the server# parameter represents a shared logical resource location that has been rescinded by the owner, return H_RESCINDED. - + @@ -9491,11 +9803,11 @@ hcall ( const uint64 H_CLEAR_HPT);]]> H_Function. - +
- +
H_IPOLL @@ -9507,19 +9819,19 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Parameters: - + - server#: The server number gotten from the + server#: The server number gotten from the “ibm,ppc-interrupt-server#s” property associated with the processor and/or tread to be interrupted. - + Semantics: - + If the value of the server# parameter specifies of one of the processors in the calling processor’s partition, then hypervisor @@ -9531,20 +9843,20 @@ hcall ( const uint64 H_CLEAR_HPT);]]> unrecoverable hardware error occurred). If the server# value is not legal, hypervisor returns H_Parameter. - + If the Shared Logical Resource option is implemented and the server# parameter represents a shared logical resource location that has been rescinded by the owner, return H_RESCINDED. - + If the partition is not in XIVE legacy mode, the Hypervisor returns H_Function. - +
@@ -9558,7 +9870,7 @@ hcall ( const uint64 H_CLEAR_HPT);]]> Syntax: - Parameters: - + H_XIRR: no input parameters defined. - + H_XIRR-X: cppr: the internal current processor priority of the calling virtual processor. Valid values in the range of 0x00 - most - favored to 0xFF - least favored less those values specified by the + favored to 0xFF - least favored less those values specified by the “ibm,plat-res-int-priorities” property in the root node). - + - + Semantics: - + Hypervisor reads the 4 byte contents of the processor’s interrupt management area port at offset BA+4 into the low order 4 bytes @@ -9598,12 +9910,12 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ the interrupt and raising the current processor priority to that of the accepted interrupt. - + Place the timestamp when the hypervisor first received the interrupt into R5. - + Hypervisor then returns H_Success or H_Hardware (if an unrecoverable hardware error occurred). @@ -9613,7 +9925,7 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ If the partition is not in XIVE legacy mode, the Hypervisor returns H_Function. - +
@@ -9634,20 +9946,20 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ On certain implementations, DMA read operations targeting the old page may still be in process for some time after the H_MIGRATE_DMA call returns; this requires that the OS not reuse/modify the data within the - old page until the worst case DMA read access time has expired. The - “ibm,dma-delay-time” property (see + old page until the worst case DMA read access time has expired. The + “ibm,dma-delay-time” property (see ) gives the OS this implementation dependent delay value. Failure to observe this delay time may result in data corruption as seen by the caller’s I/O adapter(s). - R1-R1--1. For the LPAR option supporting the hcall-migrate function - set: The platform must supply the - “ibm,dma-delay-time” property under the + set: The platform must supply the + “ibm,dma-delay-time” property under the /rtas node of the device tree. Memory pages may be simultaneously mapped by multiple DMA agents, with different translation table formats and operation characteristics. @@ -9661,9 +9973,9 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ procedures, the specific mapping table and mapping table entry. - + - R1-R1--2. For the LPAR option supporting the hcall-migrate function @@ -9671,9 +9983,9 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ DMA using any of the platform supported DMA agents. - + - R1-R1--3. For the LPAR option supporting the hcall-migrate function @@ -9690,21 +10002,21 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ provides a significantly more robust implementation. It is the intent of this architecture to have all memory in the platform have the capability to be migrated. However, on the rare - implementation that cannot meet that intent, the + implementation that cannot meet that intent, the “ibm,no-h-migrate-dma” property may be - provided in + provided in memory nodes for which H_MIGRATE_DMA cannot be implemented. - + - R1-R1--4. For the LPAR option supporting the hcall-migrate function - set: If a memory node cannot support H_MIGRATE_DMA, then that - memory node must contain the + set: If a memory node cannot support H_MIGRATE_DMA, then that + memory node must contain the “ibm,no-h-migrate-dma” property. For the I/O Super Page option the I/O page size is an attribute of the specified LIOBN (I/O pages mapped by a given LIOBN are a uniform @@ -9730,14 +10042,14 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */ to specify the power of two size of the super page. - + - R1-R1--5. For the I/O Super Page option: the platform must - support the setting by the client of byte 3 bit 0 of the - ibm,architecture.vec 5 as input to the + support the setting by the client of byte 3 bit 0 of the + ibm,architecture.vec 5 as input to the ibm,client-architecture-support method. @@ -9775,58 +10087,58 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA Parameters: - + newpage (The Logical address of the new page to be the target of the TCE translations) - + xlates (The Logical address of a list of translations against the target page the format of this list is: - + List starts on a page (4 K) boundary. - + Contains up to 256 translation entries: - + First 4 bytes of a translation entry is the logical bus number as from either the: - + “ibm,dma-window” property - + or the reserved LIOBN 0xFFFFFFFF. - + - + Next 12 bytes of a translation entry is the logical bus offset (I/O bus address). The format of the I/O bus address is dependent upon the DMA agent: - + For 32 bit PCI, the high order 8 bytes are reserved with the low order 4 bytes containing a 4 K aligned address (low order 12 bits =zero). - + For 64 bit PCI, the high order 4 bytes are reserved with the low order 8bytes containing a 4 K aligned address (low order 12 bits =zero). - + For the I/O Super Page option the very first translation entry passed is for the largest I/O page to be migrated by this sequence of @@ -9840,24 +10152,24 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA real address of the start of the page to be migrated (the low order N bits = zero). - + - + - + - + length (Number of entries in translation list is less than or equal to 256) - + If the total number of translation entries in the xlates list is less than or equal to 256 then the “length” parameter is the number of translation entries. - + For the I/O Super Page option and specifying more than 256 translation entries, the client makes a series of calls, each passing 256 @@ -9867,62 +10179,62 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA call in the initiating sequence the “length” parameter is positive as above. - + - + - + Semantics: - + For the I/O Super Page option: determine if a migration operation is in process for this “newpage” address: - + Then: - + If the previous hcall() for the migration operation was more than 1 second ago, return H_Aborted. - + If the length parameter value is zero then abort the migration operation and return H_TERM. - + If the length parameter value is not the next expected in the sequence return H_P3. - + Record the new xlates - + If the length parameter is less than zero return H_CONTINUE. - + - + Else - + If the number of outstanding operations is more than an - implementation specific number as communicated in the + implementation specific number as communicated in the “ibm,vec-5” property then return H_Resource - + If the length parameter is less than zero, initiate a new migration operation for the “newpage” address. (Note @@ -9931,65 +10243,65 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA Implementations may, in unusual cases, use a busy return code to wait for the release of resources from an immanently completing operation. - + The first xlate entry specifies the length and starting address of the page to be migrated, if this specification is invalid (unsupported length, the address is invalid for the partition, or not aligned to the length) return H_MEM_PARM. - + If the operation specifies more than an implementation specific - number of xlates as communicated in the + number of xlates as communicated in the “ibm,vec-5” property then return H_Resource. - + - + - + Check that the page to be migrated can be migrated, else H_PARAMETER. - + Check that the newpage is within the allocated logical page range of the calling partition and the address is aligned to the I/O page size of the first translation entry passed else H_PARAMETER. - + If the Shared Logical Resource option is implemented and the newpage parameter represents a shared logical resource location that has been rescinded by the owner, return H_RESCINDED. - + - + The contents of the xlates buffer are checked. - + This may be done as each entry is used, or it may be done prior to starting the operation. - + If the former, then partial processing must be backed out in the case of a detected parameter error. - + If the later, then the translation entries must be copied into an area that is not accessible by the calling OS to prevent parameter corruption after they have been verified. The OS perceived reentrancy of the function is not diminished if this option is chosen. - + @@ -10000,8 +10312,8 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA The length parameter is between (for the I/O Super Page option: the negative of the maximum number of xlate entries supported as - indicated in the - “ibm.architecture-vec-5” property of the + indicated in the + “ibm.architecture-vec-5” property of the /chosen device tree node else 1) and 256 else H_PARAMETER. @@ -10021,52 +10333,52 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA Each logical bus offset is within the allocated range of the calling partition else H_PARAMETER. - + If the Shared Logical Resource option is implemented and the logical bus offset represents a shared logical resource location that has been rescinded by the owner, return H_RESCINDED. - + Check the logical bus number: - + Is allocated to the calling partition else H_PARAMETER. Or: If the Shared Logical Resource option is implemented and the logical bus number represents a shared logical resource location that has been rescinded by the owner, return H_RESCINDED. - + For the I/O Super Page option: if the LIOBN implies a larger page size than that specified by the first translation entry for this migrate operation, place the index of the translation entry (0-255) into register R4 and return H_PGSB_PARM. - + If the LIOBN referenced an unsupported DMA agent, place the index of the translation entry (0-255) into register R4 and return H_Function. - + If the logical bus number is not supported, return H_PARAMETER. - + Note: The following is written from the perspective of a PCI DMA agent; other DMA agents may require a different sequence of - operations to achieve equivalent results. + operations to achieve equivalent results. - + - + The hypervisor disables arbitration for the IOA(s) associated with the translation entries. (In some cases, where multiple IOAs share a @@ -10074,40 +10386,40 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA firmware assigned the bus address ranges to each IOA so knows which IOAs correspond to which translation.) - + Waits for outstanding DMA write activity to complete. (This is accomplished by doing a load from an appropriate register the bridge(s) closest to the IOA -- when the load completes (dependency on load data is satisfied) all DMA write activity has completed.) - + The hypervisor copies the contents of the 4 K page originally accessed by the TCE(s) to the page referenced by the newpage value. - + The hypervisor translates the logical address within the newpage parameter and stores the resultant value in the TCE table entries specified by the translation entries. - + Executes a sync operation to ensure that the new TCE data is visible. - + The hypervisor enables arbitration on the IOA(s) associated with the translation entities and returns H_Success. - + Implementation Notes: - + The firmware should be written to minimize the arbitration disable time. The old page should be read into cache (possibly using the @@ -10130,11 +10442,11 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA own “ibm,dma-window” property specification. - +
- +
Performance Monitor Support hcall()s @@ -10158,49 +10470,49 @@ hcall ( const uint64 H_PERFMON, /* Function code */ Parameters: - + mode-set Platform specific modes to be set by this call - + mode-reset Platform specific modes to be reset by this call - + - + Semantics: - + mode-set bit(s) check for platform specific validity else H_PARAMETER - + mode-reset bit(s) check for platform specific validity else H_PARAMETER - + if any mode-set bits are set, activate corresponding mode(s) - if logically capable else H_RESOURCE - + if any mode-reset bits are on, deactivate corresponding mode(s) - if logically capable else H_RESOURCE - + place current state of platform specific modes in R4, return H_Success - + - + Defined Perfmon mode bits: bit 0: 1= Enable Perfmon @@ -10220,7 +10532,7 @@ hcall ( const uint64 H_PERFMON, /* Function code */ - R1-R1--1. For the LRDR Option: The platform must implement the @@ -10229,12 +10541,12 @@ hcall ( const uint64 H_PERFMON, /* Function code */ . - + - R1-R1--2. - For the LRDR Option: The platform must present the + For the LRDR Option: The platform must present the “ibm,h-get-dma-xlates-limited-supported” property in all PCI host bridge OpenFirmware nodes for which the H_GET_DMA_XLATES_LIMITED hcall() is supported for all child @@ -10269,73 +10581,73 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin Parameters: - + Register R4: Logical I/O Bus Number (LIOBN) - + Bits 0-31are reserved and set to zero. - + Bits 32-63 contain a 32-bit unsigned binary integer that identifies a translation which may have one or more entries that translate to a page within a range specified by the Start and End logical addresses. - + - + Register R5: Start Logical Address (SLA) - + Register R6: End Logical Address (ELA) - + Register R7: Start I/O Bus Address (SIOBA) of the translation specified by the LIOBN - + The SIOBA register may specify a special value of -1 or a starting IOBA - + - + Register R8: End I/O Bus Address (EIOBA) of the translation specified by the LIOBN - + The EIOBA register may specify a special value of -1 or an ending IOBA - + - + Semantics: - + Check that the specified LIOBN is supported and allocated to the calling logical partition, else H_PARAMETER. - + Check that the specified start logical address (SLA) is within the allocated range of the calling logical partition, and is designated on a 4 K-byte boundary, else H_P2. - + Check that the End logical address (ELA) minus 4K is within the allocated range of the calling logical partition, and is designated on a @@ -10344,54 +10656,54 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin partition yet include the last partition page in the range of the test.) - + Check that the specified starting logical address (SLA) is less than the specified ending logical address (ELA), else H_P2. - + Check that the page specified by the logical addresses within the specified range is within the allocated range of the calling logical partition and the address is 4 K-byte aligned else H_P2. - + Check the content of SIOBA - + If a value other than -1 is specified, check that the specified start I/O bus address (SIOBA) is not outside of the range of IOBAs for the specified LIOBN, else H_P4. - + If the SIOBA specifies a value of -1, the hypervisor starts the search at the lowest IOBA in the translation table, otherwise the search starts at the address specified by the SIOBA. - + - + Check the content of EIOBA - + If a value other than -1 is specified, check that the specified ending I/O bus address (EIOBA) is not outside of the range of IOBAs for the specified LIOBN, else H_P5. - + If the EIOBA specifies a value of -1, the hypervisor ends the search at the highest IOBA in the translation table, otherwise the search ends at the address specified by the EIOBA. - + - + @@ -10400,87 +10712,87 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin Place the I/O bus address and corresponding logical address into the respective registers: - + Register R4: I/O Bus Address (IOBA) - + This register contains a 64-bit unsigned binary integer that specifies the I/O bus address of the page within the specified logical address range for the specified LIOBN. - + The IOBA is returned when the hcall() completes with either H_PARTIAL, H_PAGE_REGISTERED, or H_IN_PROGRESS return codes. - + - + Register R5: Corresponding Logical Address (CLA) - + This register contains a 64-bit unsigned binary integer that designates the logical address of a page within the specified range that corresponds to the I/O bus address. - + If the hcall() completes with H_IN_PROGRESS return code, the corresponding logical address (CLA) is not returned. - + - + When the hcall() completes with H_PARTIAL or H_PAGE_REGISTERED return code: - + The I/O bus address (IOBA) and corresponding logical address (CLA) are returned. - + - + When the hcall() completes with H_PAGE_REGISTERED return code: - + The I/O bus address (IOBA) is for the final page of the translation table for the specified LIOBN as limited by the EIOBA parameter. - + - + When the hcall() completes with H_IN_PROGRESS return code: - + The current IOBA being searched against the specified range is returned, but the corresponding logical address is not returned. - + The hcall can be reissued by specifying the IOBA as the starting IOBA without incrementing the IOBA by the resource page size. - + - + Firmware Implementation Notes: - + When the H_GET_DMA_XLATES_LIMITED hcall() is issued, the hypervisor searches the translation table designated by the specified @@ -10501,11 +10813,11 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin return code, or H_Success, if the end of the translation table, as specified by the EIOBA parameter, is reached. - - + + Software Implementation Notes: - + When the hcall() completes with H_PARTIAL return code, the stored IOBA is incremented by the page size of the resource corresponding @@ -10530,7 +10842,7 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin address register, the program should check that the specified SIOBA value is not the same as the returned IOBA. - +
@@ -10562,22 +10874,22 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin The following is a list of RTAS functions that are not defined or implemented when the LPAR option is active: - + restart-rtas - R1-R1--1. For the LPAR option: The platform must implement the PowerPC External Interrupt option. - + - R1-R1--2. For the LPAR option: The Firmware must initialize each @@ -10586,18 +10898,18 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin control of the processor to the OS. - + - R1-R1--3. For the LPAR option: The RTAS rules of serialization of RTAS calls must only apply to a partition and not to the system. - + - R1-R1--4. For the LPAR option: The hypervisor cannot trust the @@ -10605,18 +10917,18 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin partition’s RTAS call parameters for validity. - + - R1-R1--5. For the LPAR option: RTAS must be instantiated within the RMA of partition storage. - + - R1-R1--6. For the LPAR option: @@ -10625,14 +10937,14 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin RTAS call definition. - + - R1-R1--7. For the LPAR option: If one or more hcalls fail due to hardware error (return status -1), the platform must make available, prior - to the completion of the next boot sequence, via an + to the completion of the next boot sequence, via an event-scan/check-exception, an error log indicating the hardware FRU responsible for such failures. Due to the asynchronous nature of error analysis, there is not a direct correlation between the log @@ -10643,8 +10955,8 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin - - + +
OF Requirements @@ -10659,8 +10971,8 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin invocation of the subset of the OF Client interface specified below appears the same to the OS image regardless of the state of the LPAR option. A model of the boot sequence is as follows: - - + + Support processor runs chip tests and configures the CPU chips. @@ -10670,7 +10982,7 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin The support processor loads the boot ROM image into System Memory along with the configuration information. - + POST code @@ -10690,7 +11002,7 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin Hypervisor RTAS - + @@ -10759,64 +11071,64 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin The client program notices that it is running on a LPAR capable machine but does not have the hypervisor bit on in the MSR so must use - hcall() routines for its PFT and TCE accesses. The presence of the + hcall() routines for its PFT and TCE accesses. The presence of the “ibm,hypertas-functions” property is a duplicate indication of LPAR mode. - + - R1-R1--1. For the LPAR option: The OF code state must be retained after all partitions are initialized pending future boot requests. - + - R1-R1--2. For the LPAR option: The OF code must recognize that logical partitioning is required as opposed to a non-LPARed system. - + - R1-R1--3. For the LPAR option: The OF must generate the device tree for the partition within the partition’s RAM. - + - R1-R1--4. For the LPAR combined with Dynamic Reconfiguration - option: The + option: The “interrupt-ranges” property for any reported interrupt source controller must report all possible interrupt - source numbers. + source numbers. - + - R1-R1--5. For the LPAR option: The OF device tree for a partition - must include in the root node, the + must include in the root node, the “ibm,partition-no” property. - + - R1-R1--6. For the LPAR option: The OF device tree for an LPAR @@ -10825,43 +11137,43 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin default partition number for the first partition created is not 1. - + - R1-R1--7. - For the LPAR option: The + For the LPAR option: The “ibm,partition-no” property value must be an integer in the range of 1 to 220-1. - + - R1-R1--8. For the LPAR option: The OF device tree for a partition - must include in the root node, the + must include in the root node, the “ibm,partition-name” property. - + - R1-R1--9. For the LPAR option: When the platform does not provide a partition manager and the one and only partition in the system owns all - the partition visible system resources, then the default value of the + the partition visible system resources, then the default value of the “ibm,partition-name” property must be the - content of the SE keyword (as displayed in the same form as the root node + content of the SE keyword (as displayed in the same form as the root node “system-id” property) with a hyphen added between the plant of manufacture and sequence number. - + - R1-R1--10. For the LPAR option: The nodes of the OF device tree @@ -10876,7 +11188,7 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin - R1-R1--11. For the LPAR option: The OF must, at the OS’s @@ -10884,9 +11196,9 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin memory region. - + - R1-R1--12. For the LPAR option: The OF must use the @@ -10894,9 +11206,9 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin boot device and configuration variables. - + - R1-R1--13. For the LPAR option: The OF must load the client @@ -10906,9 +11218,9 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin whether or not to use LPAR page management. - + - R1-R1--14. For the LPAR option: The platform must initialize the @@ -10916,9 +11228,9 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin to turning over control of the processor to a client program. - + - R1-R1--15.