From f127791962e86636ae441985aa5f6b82b80c0a6b Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Fri, 10 Apr 2020 16:29:03 -0500 Subject: [PATCH] Add Coherent Platform Facilities (CAPI) Signed-off-by: Jeff Scheel --- DeviceTree/ch_devtree_system.xml | 961 +++++- Error Handling/app_capi_error_handling.xml | 360 +++ Error Handling/bk_main.xml | 1 + Platform/ch_product_topology.xml | 2123 ++++++------- Platform/ch_system_reqs.xml | 15 + RTAS/sec_rtas_get_indices.xml | 869 ++++-- Virtualization/ch_dynamic_reconfig.xml | 1177 +++---- Virtualization/ch_lpar_option.xml | 3238 +++++++++++++++++++- Virtualization/ch_virtual_io.xml | 6 +- 9 files changed, 6860 insertions(+), 1890 deletions(-) create mode 100644 Error Handling/app_capi_error_handling.xml diff --git a/DeviceTree/ch_devtree_system.xml b/DeviceTree/ch_devtree_system.xml index 5c23ed1..0d554a6 100644 --- a/DeviceTree/ch_devtree_system.xml +++ b/DeviceTree/ch_devtree_system.xml @@ -562,7 +562,7 @@ If the boot sequence is interrupted by the multiboot key sequence, 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 + 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: @@ -1259,6 +1259,22 @@ Logical Port + + + COPLATFAC + + + Coherent Platform Facility + + + + + COPLATFUN + + + Coherent Platform Function + + @@ -4666,7 +4682,7 @@ followed by N integers encoded as with encode-int each representing - current number of unique asso- ciativity domains the platform supports at that level. + current number of unique associativity domains the platform supports at that level. @@ -8812,6 +8828,947 @@ +
+ <literal>/ibm,coherent-platform-facility node</literal> + + The ibm,coherent-platform-facility nodes + represent the coherent platform facilities. Standard property names associated + with the ibm,coherent-platform-facility node + have special values as specified below. + + + Three-cell addresses encoded with encode-phys shall be formatted as follows: + + + + When the hh...hh and ll...ll fields are concatenated to form a larger + number, hh...hh is the most significant portion and ll...ll is the least + significant portion. + + + + “#address-cells” + + Standard property name, encoded as with + encode-int, + that specifies the number of cells required to represent a child’s + bus address. The value of + “#address-cells” + for the child's bus address shall be 3. + + + + + + “#size-cells” + + Standard property name, encoded as with + encode-int, + that specifies the number of size cells required to represent a child’s + bus address. Shall have the value of 2 indicating that a child node may + take physical address space. + + + + + + “compatible” + + Standard property name per + + specifying the programming models that are compatible with this coherent + platform facility. The last value of this property shall be + “ibm,coherent-platform-facility”. + + + + + + “name” + + Standard property name per + + to define the name of the package. This property is encoded with + encode-string + and the value shall be: + “ibm,coherent-platform-facility”. + + + + + + “model” + + Standard property name per + + to define a manufacturer’s model number. This value defines the programming + version of the facility and has the value of the coherent platform + facility PSL version. + + + + + + “reg” + + Standard + property name that defines the coherent platform + facility handle. + + + prop-encoded-array: List of + (phys-addr, size) specifications. + + + + phys-addr is encoded as with + encode-phys and + size is encoded with + encode-int. + + + + The first value of the property shall be the handle for use with + the coherent platform facility, where + phys-addr + denotes the unit-address. It shall have a size value of 0. This + value is always present. + + + + + “ranges” + + Standard + property name to define the mapping of the parent + address space to child address spaces. + + + prop-encoded-array: List of + (child-phys, parent-phys,size) specifications. + + + + child-phys is an addresss, encoded as with + encode-phys, and + is the child address and shall have a type field indicating Memory Mapped + Address. + + + parent-phys is encoded as with + encode-phys and + is the parent address. + + + size is encoded with + encode-int. + + + + + + + “ibm,loc-code” + + Property name Property name specifying the unique and persistent + location code associated with this coherent platform facility p + resented as an encoded array as with + encode-string. + The value shall be of the form specified in Ux-Px-Cx. + + + + + + “interrupt-ranges” + + Standard property name specifying the + interrupt-source number(s) and range(s) associated with this coherent + platform facility. The property is presented as an encoded array of + two cells per entry, each cell encoded as with + encode-int, + with the first cell of an entry containing the first interrupt source + number (ISN 1) of a range and the second cell of an entry containing + an unsigned integer, specifying the count (N) of ISNs in the range, + such that ISN11+(N-1) specifies the value of the last + ISNN in the range. + + The interrupt source numbers are assigned and utilized by the children of this node, + ibm,coherent-platform-function. + + + + + “device_type” + + Standard + property name string encoded as with + encode-string that defines the device type of the + node. For the coherent platform facility, the device type the value shall + be the string “capi”. + + + + + Optionally the + /ibm,coherent-platform-facility + node may contain the following properties. + + + + “ibm,my-drc-index” + + + property name denotes an integer index (value of the + entry in the + “ibm,drc-indexes” property) for the + connector between the node and the node’s parent. The presence of + this indicates that the resource is dynamically reconfigurable. + + prop-encoded-array: An array of integers encoded as + with + encode-int. + + + + + “ibm,drc-indexes” + + + property name denotes an integer index to be used to + communicate to the firmware what connector is to be operated upon for the + various RTAS calls used for DR. + + prop-encoded-array: An integer encoded as with + encode-int specifying + the number of items in the following list, followed by a list of integers also + encoded as with + encode-int. + + + + + “ibm,drc-names” + + + property name describes the external labeling of the + DR connectors. + prop-encoded-array: An integer encoded as with + encode-int specifying + the number of items in the following list, followed by a list of strings each + encoded as with + encode-string. + + The values shall be the location code for each child node. + + + + + “ibm,drc-types” + + + property name, describes the type of each connector + associated with the node, in a human-readable form. + + prop-encoded-array: An integer encoded as with + encode-int + specifying the number of items in the following list, followed by a list of strings each + encoded as with + encode-string. + + + + + “ibm,drc-power-domains” + + + property name gives the power domain number for each + connector associated with the node. + + prop-encoded-array: An integer encoded as with + encode-int + specifying the number of items in the following list, followed by a list of integers also + encoded as with + encode-int. + A value other than -1 indicates that the coherent platform facility + power is controlled by the + set-power-level RTAS call. A value of -1 indicates that no + set-power-level RTAS call is required. + + + + + “ibm,phandle” + + Package handle for the coherent-platform-facility. + + + + + “ibm,cai-version” + + Property name, encoded with + encode-int, + that describes the CAIA version of the coherent platform facility. + + + + + “ibm,psl-revision” + + Property name, encoded with + encode-int, + that describes the PSL revision of the coherent platform facility. + + + + + “ibm,vpd-size” + + The size in bytes, encoded as with + encode-int, + or the VPD for the ibm,coherent-platform-facility. + This value is used to size the buffer in H_CONTROL_CA_FACILITY with + operation Collect VPD. + + + + + “status” + + Standard + property name to indicate the operational status + of this device. + + prop-encoded-array: Text string, encoded with + encode-string. + If this property is present, the value is a string indicated the + status of the device, as follows: + + + "okay" + + The device is believed to be operational. + + + + "disabled" + + The device represented by this node is not operation, but it + might become operational in the future (e.g., an external switch + is turned off, or something isn’t plugged in.) + + + + "fail" + + The device represented by this node is not operational + because a fault has been detected, and it is unlikely that the + device will become operational without repair. No additional + failure details are available. + + + + "fail-xxx" + + The device represented by this node is not operational + because a fault has been detected, and it is unlikely that + the device will become operational without repair. “xxx” is + additional human-readable information about the particular + fault condition that was detected. + + + + The absence of this property means that the operational status is + unknown or okay. + + + + + “ibm,privileged-facility” + + Property name, encoded as with + encode-int, + that specifies if the ibm,coherent-platform-facility + is privileged. The absence of this property or a property of 0 + indicates the facility is not privileged. + + + + + “vendor-id” + + Vendor ID from PCI header for the + ibm,coherent-platform-facility + + + + + “device-id” + + Device ID from PCI header for the + ibm,coherent-platform-facility + + + + + “revision-id” + + Revision ID from PCI header for the + ibm,coherent-platform-facility + + + + + “class-code” + + Class Code from PCI header for the + ibm,coherent-platform-facility + + + + + “subsystem-vendor-id” + + Subsystem Vendor ID from PCI header for the + ibm,coherent-platform-facility + + + + + “subsystem-id” + + Subsystem ID from PCI header for the + ibm,coherent-platform-facility + + + + +
+ Children of the /ibm,coherent-platform-facility node + + The + ibm,coherent-platform-function + nodes are the children of the + /ibm,coherent-platform-facility + node represent the individual platform facility functions. Standard property + names associated with the children of the + /ibm,coherent-platform-facility + node have special values as specified below. Note the children of the + /ibm,coherent-platform-facility + node shall contain the following standard properties with their standard + definitions: + + + + “compatible” + + Standard property name per + + specifying the programming models that are compatible with this coherent + platform function. A value may be present such as “capiVVVV,DDDD.SSSS.ssss”, + where VVVV is “vendor-id”, DDDD is “device-id”, SSSS is “subsystem-vendor-id” + and ssss is “subsystem-id”. The last value of this property shall be + “ibm,coherent-platform-function”. + + + + + + “name” + + Standard property name per + + to define the name of the package. This property is encoded with + encode-string + and the value shall be: + “ibm,coherent-platform-function”. + + + + + + “reg” + + Standard + property name that defines the coherent platform + function device handle and mmio address regions. + + + prop-encoded-array: List of + (phys-addr, size) specifications. + + + + phys-addr is encoded as with + encode-phys, + indicating an address relative to value of the associated + assigned-address value. + + + Size is encoded with + encode-int. + + + + The first value of the property shall be the handle for use in + hypervisor calls to the coherent platform function. It shall have a + type of Unit Address and size value of 0. This value is always present. + + Optionally additional values may be present that specify if + the coherent-platform-function has access to PSL Privilege 2 Area + or AFU Problem State Area indicated by the type field in the + phys-addr. + + To calculate the address of memory-mapped area the + assigned-address phys.mid,phys.lo + field is added to the reg + phys.mid,phys.lo field for the matching area + to give the calculated address. + + + + + “assigned-addresses” + + Property name that defines the coherent platform + function assigned mmio address regions. + + + prop-encoded-array: List of + (phys-addr, size) specifications. + + + + phys-addr is encoded as with + encode-phys + and denotes the assigned addresses for each register set. + + + size is encoded with + encode-int. + + + + + + + + “ibm,loc-code” + + Property name specifying the unique and persistent location + code associated with this coherent platform function presented + as an encoded array as with + encode-string. + The value shall be of the form specified in Ux-Px-Cx-Sy-Sz, + where y is a logical platform function unit number and z is the + virtual function unit number. + + + + + + Optionally a child node of the + /ibm,coherent-platform-facility + node with the + “name” of + “ibm,coherent-platform-function” + may contain as appropriate the following unique properties: + + + + “device_type” + + Standard + property name string encoded as with + encode-string that defines the device type of the + node. For the coherent platform device type the value shall + be the string “ibm,coherent-accel”. + + + + + “ibm,my-drc-index” + + + property name denotes an integer index (value of the + entry in the + “ibm,drc-indexes” property) for the + connector between the node and the node’s parent. The presence of + this indicates that the resource is dynamically reconfigurable. + + prop-encoded-array: An array of integers encoded as + with + encode-int. + + + + + “ibm,#processes” + + Property name, encoded as with + encode-int, that + defines the number of operating system processes that can be concurrently + attached to the coherent accelerator function via the H_ATTACH_CA_PROCESS + hcall. + + + + + “ibm,scratchpad-size” + + + Property name that specifies the size of the + scratch pad area supported by the coherent platform function in terms + of cells. The absence of this parameter or a value of 0 indicates the + coherent platform function does not support a scratch pad area. + + prop-encoded-array: Consisting of two integers + (value-hi, value-lo) + each encoded as with + encode-int, + such that their combined value is (value-hi || + value-lo). + + + + + “ibm,programmable” + + Property name, encoded as with + encode-int, that + specifies if the coherent platform function can be programmed + (via H_DOWNLOAD_CA_FUNCTION) with a value of 1. The absence of this + parameter or a value of 0 indicates the coherent platform function + does not support programming. + + + + + “ibm,phandle” + + Package handle for the coherent-platform-function. + + + + + “ibm,max-ints-per-process” + + Property name, encoded as with + encode-int, that + specifies the maximum number of interrupts from the + “interrupt-ranges” + property of the ibm,coherent-platform-facility + that can be assigned per process with the H_ATTACH_CA_PROCESS hcall. + + + + + “ibm,min-ints-per-process” + + Property name, encoded as with + encode-int, that + specifies the minimum number of interrupts from the + “interrupt-ranges” + property of the ibm,coherent-platform-facility + that must be assigned per process with the H_ATTACH_CA_PROCESS hcall. + + + + + “ibm,max-ints” + + Property name, encoded as with + encode-int, that + specifies the maximum number of interrupts from the + “interrupt-ranges” + property of the ibm,coherent-platform-facility + that can be assigned for all processes attached on the + coherent-platform-function. + + + + + “ibm,vpd-size” + + The size in bytes, encoded as with + encode-int, + for the VPD for the ibm,coherent-platform-function. + This value is used to size the buffer in H_CONTROL_CA_FUNCTION with + operation Collect VPD. + + + + + “ibm,error-buffer-size” + + + Property name that specifies the error buffer size + for the ibm,coherent-platform-function. This + value is used in H_CONTROL_CA_FUNCTION with operation Get Error Buffer. + + prop-encoded-array: Consisting of two integers + (value-hi, value-lo) + each encoded as with + encode-int, + such that their combined value is (value-hi || + value-lo). + + + + + “ibm,config-record-type” + + Property name, encoded as with + encode-int, + that specifies the type of the configuration record for the + ibm,coherent-platform-function. + This value is used to identify the format of the Function Configuration + Record and is defined by the CAIA. + + + + + “ibm,config-record-size” + + + Property name that specifies the size of each configuration + record for the ibm,coherent-platform-function. This + value is used in H_CONTROL_CA_FUNCTION with operation Get Function + Configuration Record + + prop-encoded-array: Consisting of two integers + (value-hi, value-lo) + each encoded as with + encode-int, + such that their combined value is (value-hi || + value-lo). + + + + + “ibm,#config-records” + + Property name, encoded as with + encode-int, + that specifies the number of the configuration records for the + ibm,coherent-platform-function. + This value is used in H_CONTROL_CA_FUNCTION with operation Get + Function Configuration Record. + + + + + “ibm,function-number” + + Property name, encoded as with + encode-int, + that specifies the function number for the + ibm,coherent-platform-function. + This value is used to call H_DOWNLOAD_CA_FUNCTION and download + images to the function. + + + + + “ibm,privileged-function” + + Property name, encoded as with + encode-int, + that specifies if the + ibm,coherent-platform-function is privileged. + The absence of this property or a property of 0 indicates the + function is not privileged. + + + + + “vendor-id” + + Vendor ID from PCI header for the + ibm,coherent-platform-function + + + + + “device-id” + + Device ID from PCI header for the + ibm,coherent-platform-function + + + + + “revision-id” + + Revision ID from PCI header for the + ibm,coherent-platform-function + + + + + “class-code” + + Class Code from PCI header for the + ibm,coherent-platform-function + + + + + “subsystem-vendor-id” + + Subsystem Vendor ID from PCI header for the + ibm,coherent-platform-function + + + + + “subsystem-id” + + Subsystem ID from PCI header for the + ibm,coherent-platform-function + + + + + “ibm,process-mmio” + + Property name, encoded as with + encode-int, + that if set to 1, defines that the coherent platform function + utilizes per-process MMIO spaces. The H_ATTACH_CA_PROCESS hcall + returns MMIO address/range information. If this property is 0 or + not present, per-process MMIO is not supported. + + + + + “ibm,process-mmio-size” + + The size in bytes of the per-process MMIO space available for + each attached process. This is the same value that will be returned + in R6 for H_ATTACH_CA_FUNCTION. If the + ibm,process-mmio + property is 0 or not present, this property will be 0 or not present. + + prop-encoded-array: Consisting of two integers + (value-hi, value-lo) + each encoded as with + encode-int, + such that their combined value is (value-hi || + value-lo). + + + + + “ibm,programming-model” + + property name, encoded as with + encode-string, + describes the programming model currently in effect for the coherent + platform function. + + The value shall be one of the following: + + + + "none" + + + "dedicated-process" + + + "shared-afu-directed" + + + "shared-time-sliced" + + + + + + + “ibm,programming-models” + + property name, describes the programming + models supported by the coherent platform function. + + prop-encoded-array: An integer encoded as with + encode-int specifying + the number of items in the following list, followed by a list of + strings each encoded as with + encode-string. + Each of the values shall be one of the possible values specified + for the + “ibm,programming-model” property. + + + + + + “ibm,supports-aur” + + Property name, encoded as with + encode-int, + that if set to 1, defines that the coherent platform function + supports an acceleration utilization record (AUR). If this + property is 0 or not present, the coherent platform function + does not support an AUR. + + + + + “ibm,supports-csrp” + + Property name, encoded as with + encode-int, + that if set to 1, defines that the coherent platform function + supports a context / save restore (CSRP). If this property is 0 + or not present, the coherent platform function does not support a CSRP. + + + + + “ibm,supports-prr” + + Property name, encoded as with + encode-int, + that if set to 1, defines that the coherent platform function + supports paged resolution responses (PRR). If this property is 0 + or not present, the coherent platform function does not support + PRR. + + + + + “ibm,function-error-interrupt” + + Property name, encoded as with + encode-int, + that defines the interrupt source number of the + ibm,coherent-platform-function + error interrupt. An interrupt on this source indicates an error + that is scoped to the entire + ibm,coherent-platform-function. + + + + +
+
diff --git a/Error Handling/app_capi_error_handling.xml b/Error Handling/app_capi_error_handling.xml new file mode 100644 index 0000000..04d72ac --- /dev/null +++ b/Error Handling/app_capi_error_handling.xml @@ -0,0 +1,360 @@ + + + + Coherent Platform Facility Error Handling and Recovery + + During the course of operation, a coherent platform function can encounter errors. + Some possible reason for errors are: + + + + Hardware recoverable and unrecoverable errors + + + Transient and over-threshold correctable errors + + + + This architecture is not meant to contain an exhaustive list of errors, + implementations can vary. + +
+ Error States + + + + + + + + + + + State + + + + + Value + + + + + Description + + + + + + + + Normal + + + 1 + + + Coherent platform function is operating normally. This is the + default state. + + + + + Disabled + + + 2 + + + Coherent platform function is operating, but all process + execution is disabled. + + + + + Temporarily Unavailable + + + 3 + + + Platform has initiated error recovery and the coherent + platform function is temporarily not available. + + + + + Permanently Unavailable + + + 4 + + + Platform has encountered a fatal error with the coherent platform + function. Recovery is impossible, without partition reboot, DLPAR + re-assignment, system reboot or hardware replacement. + + + + + +
+ +
+ Coherent Platform Function State Transitions + + + + + + + + + + + + Initial State + + + Final State + + + + + 1 + Normal + + + 2 + Disabled + + + 3 + Temporarily Unavailable + + + 4 + Permanently Unavailable + + + + + + + 1Normal + + + +   + + + Platform initiated action + + + Platform initiated action during recovery / + H_CONTROL_CA_FUNCTION Read Error State + + + Platform detected permanent error + + + + + 2Disabled + + + H_CONTROL_CA_FUNCTION / Reset or Partition Reboot / + DLPAR re-assignment + + + +   + + + Platform initiated action + + + Platform detected permanent error + + + + + 3Temporarily Unavailable + + + + Not a valid transition, must go through state 2 + + + Platform initiated action after recovery + + + +   + + + Platform detected permanent error + + + + + 4Permanently Unavailable + + + Partition reboot or DLPAR reassignment + + + + Not a valid transition + + + H_CONTROL_CA_FACILITY / Reset + + + +   + + + + + +
+ +
+ General Error Recovery Procedure + + The following flow is a description of the general error recovery steps + required to reset operation of the coherent platform function. This recovery + is initiated by platform firmware or after an error is detected by the OS. + + + + If necessary, platform firmware freezes OS MMIO access for coherent + platform function, error information is col- lected and cached in platform + firmware for later retrieval by OS. + + + Platform firmware terminates and removes all processes and disables + coherent platform function if possible. + + + The error state for the coherent platform function changes to + Temporarily Unavailable. + + + Platform firmware resets and reconfigures hardware associated with + coherent platform function. + + + Platform firmware unfreezes OS MMIO access and sets coherent + platform function to Disabled. + + + OS calls H_CONTROL_CA_FUNCTION with operation of “Read Error State” + until it observes state of Disabled. + + + Optionally, OS collects any coherent platform function error data via + H_CONTROL_CA_FUNCTION with operation of “Get Error Buffer” and “Get Error + Log”. + + + OS calls H_CONTROL_CA_FUNCTION with operation of “Get Download Status” + in order to determine if a download is required for the coherent platform + function, if so, OS performs the download. After the download the coherent + platform function is still in Disabled error state. + + + OS calls ibm,update-nodes and + ibm,update-properties for the affected + coherent platform facility in order to receive current configuration values. + + + OS uses H_CONTROL_CA_FUNCTION with operation of “Reset” to change the + coherent platform function error state back to Normal. + + +
+ +
+ OS Application Detected Error + + Application detects an error, using implementation dependent methods. + + + + Application detects an error and determines a reset is necessary. + + + Application asks the OS to perform a reset to the AFU. + + + OS calls H_CONTROL_CA_FUNCTION with operation of “Reset”. + + + Platform firmware performs a reset to the coherent platform function. + See H_CONTROL_CA_FUNCTION with “Reset” operation for details. + + + OS receives return code from H_CONTROL_CA_FUNCTION indicating if the + reset was successful. + + + If necessary, the OS can performs a download of the coherent platform + function via H_DOWNLOAD_CA_FUNCTION. + + + OS then re-attachs process contexts as necessary and the application + resumes normal operation. + + + If Reset operation does not clear error, OS should signal serviceable + error to HMC and discontinue use of coherent platform function. + + +
+ +
+ Application Download + + There are some instances in which the OS would like to re-download a c + oherent platform function in operation. This could be due to unexpected + behavior or bad state. + + + + OS resets the coherent platform function by calling + H_CONTROL_CA_FUNCTION with operation of “Reset”. The reset + clears the download state. + + + OS performs download to coherent platform function using + H_DOWNLOAD_CA_FUNCTION and after a successful download. + + + OS calls ibm,update-nodes and + ibm,update-properties for the affected + coherent platform facility in order to receive current configuration values. + + + OS can attach processes and proceed with operation. + + +
+ diff --git a/Error Handling/bk_main.xml b/Error Handling/bk_main.xml index 1e16af6..b192c62 100644 --- a/Error Handling/bk_main.xml +++ b/Error Handling/bk_main.xml @@ -336,6 +336,7 @@ + diff --git a/Platform/ch_product_topology.xml b/Platform/ch_product_topology.xml index 4a2c1b8..0aeafea 100644 --- a/Platform/ch_product_topology.xml +++ b/Platform/ch_product_topology.xml @@ -1,419 +1,419 @@ - Product Topology
VPD and Location Code OF Properties - A set of OF properties is defined to facilitate asset protection and - RAS capabilities in LoPAR systems. The following properties are defined in + A set of OF properties is defined to facilitate asset protection and + RAS capabilities in LoPAR systems. The following properties are defined in ): - + “ibm,vpd” - + “ibm,loc-code” - + - R1-R1--1. - Each instance of a hardware entity (FRU) has a platform unique - location code and any node in the OF device tree that describes a part of a - hardware entity must include the - “ibm,loc-code” property with a value that represents + Each instance of a hardware entity (FRU) has a platform unique + location code and any node in the OF device tree that describes a part of a + hardware entity must include the + “ibm,loc-code” property with a value that represents the location code for that hardware entity. - + - R1-R1--2. - OF nodes that do not represent an instance - of a hardware entity (FRU) do not have a location code and thus these nodes, + OF nodes that do not represent an instance + of a hardware entity (FRU) do not have a location code and thus these nodes, except for the OF root node, do not include the “ibm,loc-code” property. - Architecture Note: In general, an OF node that has a unit address - corresponds to an instance of a hardware entity and a node that does not have a - unit address does not correspond to an instance of a hardware entity. The nodes - for caches are one exception to this statement. Note that the OF - openprom node is a system node and thus should have neither the - “ibm,loc-code” property nor the + Architecture Note: In general, an OF node that has a unit address + corresponds to an instance of a hardware entity and a node that does not have a + unit address does not correspond to an instance of a hardware entity. The nodes + for caches are one exception to this statement. Note that the OF + openprom node is a system node and thus should have neither the + “ibm,loc-code” property nor the “ibm,vpd” property. - + - R1-R1--3. - If a hardware entity contains unique VPD information and the - entity corresponds to a node in the OF device tree, then that device tree node + If a hardware entity contains unique VPD information and the + entity corresponds to a node in the OF device tree, then that device tree node must include the “ibm,vpd” property. - + - R1-R1--4. - An instance of a hardware entity (FRU) must - have one and only one “ibm,vpd” property - element that defines the VPD keywords specified in Requirement + An instance of a hardware entity (FRU) must + have one and only one “ibm,vpd” property + element that defines the VPD keywords specified in Requirement . - Platform Implementation Note: In general, an - instance of a hardware entity has a single “ibm,vpd” - property element that is in one of the nodes that also contains an - “ibm,loc-code” property element for that + Platform Implementation Note: In general, an + instance of a hardware entity has a single “ibm,vpd” + property element that is in one of the nodes that also contains an + “ibm,loc-code” property element for that entity. - + - R1-R1--5. - An OF device tree node that includes the - “ibm,vpd” property must also include an - “ibm,loc-code” property, where each - property has the same number of elements and the matching elements of both - properties define the same instance of a hardware entity (FRU), where matching - elements are defined as the nth string of the “ibm,loc-code” - property and the nth set of tags in - the “ibm,vpd” property for all values of + An OF device tree node that includes the + “ibm,vpd” property must also include an + “ibm,loc-code” property, where each + property has the same number of elements and the matching elements of both + properties define the same instance of a hardware entity (FRU), where matching + elements are defined as the nth string of the “ibm,loc-code” + property and the nth set of tags in + the “ibm,vpd” property for all values of n. - + - R1-R1--6. - VPD data that is not associated with an instance of a hardware - entity (FRU) that is described by a single OF device tree node must be reported - in an appropriate OF node using the “ibm,loc-code” and + VPD data that is not associated with an instance of a hardware + entity (FRU) that is described by a single OF device tree node must be reported + in an appropriate OF node using the “ibm,loc-code” and “ibm,vpd” properties. Architecture Notes: - + - The root node is the appropriate OF node (for Requirement ) for any instance of a hardware entity that - cannot be dynamically reconfigured. Any one and only one of the OF nodes that - describe the dynamically reconfigurable entity can contain the properties for + The root node is the appropriate OF node (for Requirement ) for any instance of a hardware entity that + cannot be dynamically reconfigured. Any one and only one of the OF nodes that + describe the dynamically reconfigurable entity can contain the properties for the dynamically reconfigurable entity case. - + - A dynamically reconfigurable entity may consist of more than one - FRU. In this case, the first element of both the “ibm,vpd” - property and the “ibm,loc-code” property for the dynamically - reconfigurable entity must define the VPD and location code for the OF device + A dynamically reconfigurable entity may consist of more than one + FRU. In this case, the first element of both the “ibm,vpd” + property and the “ibm,loc-code” property for the dynamically + reconfigurable entity must define the VPD and location code for the OF device tree node that includes those properties. - + - A FRU can be considered dynamically reconfigurable if the hardware - is enabled for dynamic reconfiguration and full platform support might be + A FRU can be considered dynamically reconfigurable if the hardware + is enabled for dynamic reconfiguration and full platform support might be implemented at a later date. - + - Platform Implementation Note: If a location + Platform Implementation Note: If a location does not return VPD, the property would contain a null entry for the VPD.
- +
System Identification - provides properties in the + provides properties in the “OF Root Node” section called “system-id” and“model”. - R1-R1--1. (Requirement Number Reserved For Compatibility) - + - R1-R1--2. - Each system enclosure (generally, a drawer), + Each system enclosure (generally, a drawer), must have the VPD SE and TM keywords (see ). - + - R1-R1--3. - The SE and TM keywords for a - master enclosure must be contained in the “ibm,vpd” - property for the master enclosure which may - also contain other keywords. A master enclosure must also have the YK keyword - if another enclosure shares the same combined SE and TM keyword values. The YK - keyword (see ) for a secondary - enclosure must be contained in the “ibm,vpd” - property for the secondary enclosure, which may also contain other - keywords. Each master enclosure with a YK keyword must have a unique YK value - that is the same as the value of the YK keyword for each of the secondary - enclosures that share the same combined SE and TM keyword values. An enclosure - is not a FRU and thus its VPD must not contain the FN, PN, SN, EC, RM or RL + The SE and TM keywords for a + master enclosure must be contained in the “ibm,vpd” + property for the master enclosure which may + also contain other keywords. A master enclosure must also have the YK keyword + if another enclosure shares the same combined SE and TM keyword values. The YK + keyword (see ) for a secondary + enclosure must be contained in the “ibm,vpd” + property for the secondary enclosure, which may also contain other + keywords. Each master enclosure with a YK keyword must have a unique YK value + that is the same as the value of the YK keyword for each of the secondary + enclosures that share the same combined SE and TM keyword values. An enclosure + is not a FRU and thus its VPD must not contain the FN, PN, SN, EC, RM or RL keywords. - + - R1-R1--4. - The enclosure must also be - represented in the corresponding element of the “ibm,loc-code” - property with the location code of the + The enclosure must also be + represented in the corresponding element of the “ibm,loc-code” + property with the location code of the enclosure for a multi-enclosure platform. - Implementation Note: The location code will be - for the full enclosure. The drawer position is the u-units counting from the + Implementation Note: The location code will be + for the full enclosure. The drawer position is the u-units counting from the bottom of the rack. Specific numbering is platform dependent. - + - R1-R1--5. - If the system contains multiple processor enclosures, firmware - must use the VPD SE field from the first or ‘marked’ processor - enclosure (see ) to + If the system contains multiple processor enclosures, firmware + must use the VPD SE field from the first or ‘marked’ processor + enclosure (see ) to construct “system-id”. - Implementation Note: What is meant by ‘marked’ above is - that, in a system, the ‘first’ processor enclosure could become - ambiguous. In such a case, a specific processor enclosure could be marked by - the firmware or HMC as being the processor enclosure to use for identification + Implementation Note: What is meant by ‘marked’ above is + that, in a system, the ‘first’ processor enclosure could become + ambiguous. In such a case, a specific processor enclosure could be marked by + the firmware or HMC as being the processor enclosure to use for identification purposes. - + - R1-R1--6. - One or more of the MI, RM, and RL keywords - must be present for any firmware specific VPD. (with a value of - “UNKNOWN” for unknown values), and must be present based on all + One or more of the MI, RM, and RL keywords + must be present for any firmware specific VPD. (with a value of + “UNKNOWN” for unknown values), and must be present based on all of the following: - + - The RL keyword must be provided if the platform does not support + The RL keyword must be provided if the platform does not support the ibm,update-flash-64-and-reboot RTAS call. - The RM keyword must be provided if the platform supports only a - single flash image updated via the ibm,update-flash-64-and-reboot - service and does not support the ibm,manage-flash-image and + The RM keyword must be provided if the platform supports only a + single flash image updated via the ibm,update-flash-64-and-reboot + service and does not support the ibm,manage-flash-image and ibm,validate-flash-image RTAS calls. - The MI keyword must be provided if the platform supports dual - flash images via the ibm,update-flash-64-and-reboot, the - ibm,manage-flash-image, and the ibm,validate-flash-image + The MI keyword must be provided if the platform supports dual + flash images via the ibm,update-flash-64-and-reboot, the + ibm,manage-flash-image, and the ibm,validate-flash-image RTAS calls. - The ML keyword must be provided if the platform supports dual - flash images via the ibm,update-flash64-and-reboot, - the ibm,manage-flash-image, and the ibm,validate-flash-image + The ML keyword must be provided if the platform supports dual + flash images via the ibm,update-flash64-and-reboot, + the ibm,manage-flash-image, and the ibm,validate-flash-image RTAS calls. - + - + - R1-R1--7. - System firmware and service processor - firmware must have VPD that is separate from the VPD of the FRU that contains - the system firmware and service processor firmware and this VPD must have a - location code that is made by adding “/Yn” to the end of the - location code for the FRU that contains the firmware where n is a platform + System firmware and service processor + firmware must have VPD that is separate from the VPD of the FRU that contains + the system firmware and service processor firmware and this VPD must have a + location code that is made by adding “/Yn” to the end of the + location code for the FRU that contains the firmware where n is a platform dependent instance of the firmware. - + - R1-R1--8. - The description (large resource type of - 0x82) for the system firmware VPD in the “ibm,vpd” - property must be “System Firmware or + The description (large resource type of + 0x82) for the system firmware VPD in the “ibm,vpd” + property must be “System Firmware or Platform Firmware”. - + - R1-R1--9. - System firmware VPD must be found in the - root node if the system supports only static VPD, - otherwise system firmware VPD must be provided via the + System firmware VPD must be found in the + root node if the system supports only static VPD, + otherwise system firmware VPD must be provided via the ibm,get-vpd RTAS call. - + - R1-R1--10. - The description (large resource type of - 0x82) for the service processor firmware VPD in the “ibm,vpd” - property must be “Service Processor - Firmware”, if the service processor firmware is a separate FRU from the + The description (large resource type of + 0x82) for the service processor firmware VPD in the “ibm,vpd” + property must be “Service Processor + Firmware”, if the service processor firmware is a separate FRU from the system firmware. - R1-R1--11. - Service processor firmware VPD must be - found in the root node if the service processor firmware is a separate FRU from + Service processor firmware VPD must be + found in the root node if the service processor firmware is a separate FRU from the system firmware. - + - R1-R1--12. - The VPD SE field (see ) - must be electronically stored in a manner that is not modifiable in a user + The VPD SE field (see ) + must be electronically stored in a manner that is not modifiable in a user environment. - + - R1-R1--13. - There must be a property, “model”, - under the root node in the format, - “<vendor>,xxxx-yyy”, where <vendor> is replaced by - one to five letters representing the stock symbol of the company (for example, - for IBM: “IBM,xxxx-yyy”), and where xxxx-yyy is derived from the - VPD TM field (see ) of the first or + There must be a property, “model”, + under the root node in the format, + “<vendor>,xxxx-yyy”, where <vendor> is replaced by + one to five letters representing the stock symbol of the company (for example, + for IBM: “IBM,xxxx-yyy”), and where xxxx-yyy is derived from the + VPD TM field (see ) of the first or ‘marked’ processor enclosure. - + - R1-R1--14. - The values of the type/model (TM) and system serial number (SE) - (see ) must remain the same even with + The values of the type/model (TM) and system serial number (SE) + (see ) must remain the same even with service or reconfiguration of the system. - Implementation Note: A change in either TM or + Implementation Note: A change in either TM or SE would indicate a system replacement as opposed to a reconfiguration. - This definition of the“system-id” - property provides extensibility and ensures that uniqueness can be - maintained. The 2 byte Field Type will serve to identify the format of the + This definition of the“system-id” + property provides extensibility and ensures that uniqueness can be + maintained. The 2 byte Field Type will serve to identify the format of the System Identifier Field which follows. - Hardware Implementation Note: It is recommended that the VPD SE field - be held in an area of the machine that is least susceptible to hardware - failure. This is to minimize the effect on software licensing when a FRU must - be changed. Another useful technique is to socket the part containing the SE + Hardware Implementation Note: It is recommended that the VPD SE field + be held in an area of the machine that is least susceptible to hardware + failure. This is to minimize the effect on software licensing when a FRU must + be changed. Another useful technique is to socket the part containing the SE field, allowing service personnel to move the old SE to the new FRU.
- +
Hardware Location Codes - Hardware location codes are used to provide a mapping of logical - functions in a platform (or expansion sites for logical functions, such as - connectors or ports) to their specific locations within the physical structure - of the platform. The description in the following section is intended to define - a standard architecture for these location codes, which would be used in three + Hardware location codes are used to provide a mapping of logical + functions in a platform (or expansion sites for logical functions, such as + connectors or ports) to their specific locations within the physical structure + of the platform. The description in the following section is intended to define + a standard architecture for these location codes, which would be used in three places: - + These location codes would be included as a property, - “ibm,loc-code”, under device nodes in - the OF device tree, to provide identification of where those device functions + “ibm,loc-code”, under device nodes in + the OF device tree, to provide identification of where those device functions are physically located in the platform. - To make service and parts replacement easier, hardware location - codes of failing components would be appended to the standard 40-byte Extended - Error Log templates returned by the RTAS event-scan and + To make service and parts replacement easier, hardware location + codes of failing components would be appended to the standard 40-byte Extended + Error Log templates returned by the RTAS event-scan and check-exception services. - + - Software Note: Since the OF device tree currently only defines the - core platform devices and IOAs, OS applications such as diagnostics may need to - extend these location codes with logical addresses to point to devices such as - SCSI (Small Computer System Interface) drives or asynchronous tty + Software Note: Since the OF device tree currently only defines the + core platform devices and IOAs, OS applications such as diagnostics may need to + extend these location codes with logical addresses to point to devices such as + SCSI (Small Computer System Interface) drives or asynchronous tty (teletypewriter) terminals. - Location Codes are globally unique within a system and are persistent + Location Codes are globally unique within a system and are persistent between system reboots and power cycles. - R1-R1--1. - All platforms must implement the + All platforms must implement the Converged Location Codes option. - + - R1-R1--2. - Location codes must be globally unique - within a system, including across multiple CECs of a clustered system, and must + Location codes must be globally unique + within a system, including across multiple CECs of a clustered system, and must be persistent across multiple system reboots and power cycles. - Converged location codesThe - term “converged” is historic, based on merging (converging) - several previous versions of location codes. are strings - composed of one or more location labels separated by dashes - (“-”). Location labels are strings that begin with a location - prefix followed by a distinguishing value. For example, the location code for a - PCI (Peripheral Component Interconnect) card in a CEC (Central Electronic + Converged location codesThe + term “converged” is historic, based on merging (converging) + several previous versions of location codes. are strings + composed of one or more location labels separated by dashes + (“-”). Location labels are strings that begin with a location + prefix followed by a distinguishing value. For example, the location code for a + PCI (Peripheral Component Interconnect) card in a CEC (Central Electronic Complex) might be something like this: @@ -422,50 +422,50 @@ xml:lang="en"> - Valid location codes consist of uppercase characters ('A' - 'Z'), - digits (0 - 9), periods ('.'), and dashes ('-'). Characters other than these - valid characters will be replaced by pound signs ('#') to protect display and - formatting routines and give a consistent indication of a problem in the data. + Valid location codes consist of uppercase characters ('A' - 'Z'), + digits (0 - 9), periods ('.'), and dashes ('-'). Characters other than these + valid characters will be replaced by pound signs ('#') to protect display and + formatting routines and give a consistent indication of a problem in the data. Periods may be used to improve readability of the location code. - The existence of the - “ibm,converged-loc-codes” property in the - root node of the device tree indicates that the platform implements + The existence of the + “ibm,converged-loc-codes” property in the + root node of the device tree indicates that the platform implements the Converged Location Codes option. - + - R1-R1--3. - For the Converged Location Codes - option: The platform must implement the “ibm,converged-loc-codes” + For the Converged Location Codes + option: The platform must implement the “ibm,converged-loc-codes” property in the root node of the device tree. - + - R1-R1--4. - For the Converged Location Codes - option: The location code contained in each instance of the - property “ibm,loc-code” must match the - format as described in the sections under and + For the Converged Location Codes + option: The location code contained in each instance of the + property “ibm,loc-code” must match the + format as described in the sections under and . - + - R1-R1--5. - For the Converged Location Codes - option: Extended error logs reported to the OS by event-scan - orcheck-exception must have the - characters “IBM<NULL>” in bytes 12-15, and include the - location codes for the failing elements in the format as described in the - sections under and + For the Converged Location Codes + option: Extended error logs reported to the OS by event-scan + orcheck-exception must have the + characters “IBM<NULL>” in bytes 12-15, and include the + location codes for the failing elements in the format as described in the + sections under and . @@ -473,23 +473,23 @@ xml:lang="en">
Converged Location Code Labels - This section describes the types of location code labels. See also - for the rules for building a location + This section describes the types of location code labels. See also + for the rules for building a location code.
Prefix Summary Table - The prefix of a converged location code is as defined in this + The prefix of a converged location code is as defined in this section. - R1-R1--1. - For the Converged Location - Codes option: The location code prefixes specified in - must be used in constructing location + For the Converged Location + Codes option: The location code prefixes specified in + must be used in constructing location codes. @@ -520,7 +520,7 @@ xml:lang="en"> A - Air handler (for example: blower, fan, motor scroll + Air handler (for example: blower, fan, motor scroll assembly, motor drive assembly). . @@ -529,10 +529,10 @@ xml:lang="en"> C - Card Connector (for example, connector for: IOA, - Processor Card, Riser Card, Daughter Card, DIMM, Regulator Card, MCM, L3 Cache, - Jumper Card, Passthru Interposer (for Processor Fabric when an MCM is not - installed), Pluggable Module Chips). + Card Connector (for example, connector for: IOA, + Processor Card, Riser Card, Daughter Card, DIMM, Regulator Card, MCM, L3 Cache, + Jumper Card, Passthru Interposer (for Processor Fabric when an MCM is not + installed), Pluggable Module Chips). . @@ -541,8 +541,8 @@ xml:lang="en"> D - Device (for example: Diskette, DASD, Operator Panel, SES - (Storage Enclosure Services) Device). + Device (for example: Diskette, DASD, Operator Panel, SES + (Storage Enclosure Services) Device). . @@ -551,7 +551,7 @@ xml:lang="en"> E - Electrical (for example: Battery, Power Supply, + Electrical (for example: Battery, Power Supply, Charger). . @@ -560,7 +560,7 @@ xml:lang="en"> F - Frame. See + Frame. See . @@ -569,8 +569,8 @@ xml:lang="en"> L - Logical Path (for example: SCSI Target, IDE Address, - ATAPI Address, Fibre Channel LUN, etc.). + Logical Path (for example: SCSI Target, IDE Address, + ATAPI Address, Fibre Channel LUN, etc.). . @@ -579,7 +579,7 @@ xml:lang="en"> M - Mechanical (Plumbing, Valves, Latches). See + Mechanical (Plumbing, Valves, Latches). See . @@ -588,7 +588,7 @@ xml:lang="en"> N - Horizontal placement for an empty rack location. See + Horizontal placement for an empty rack location. See . @@ -597,7 +597,7 @@ xml:lang="en"> P - Planar (for example: Backplane, Board). + Planar (for example: Backplane, Board). . @@ -606,8 +606,8 @@ xml:lang="en"> R - Resource (identifies a resource that is not a FRU, but - needs identification in the error log). See + Resource (identifies a resource that is not a FRU, but + needs identification in the error log). See . @@ -616,7 +616,7 @@ xml:lang="en"> S - SR-IOV adapter virtual function. See + SR-IOV adapter virtual function. See . @@ -625,8 +625,8 @@ xml:lang="en"> T - Port (for example: Port, Connector, Cable Connector, - Jack, Interposer). + Port (for example: Port, Connector, Cable Connector, + Jack, Interposer). . @@ -635,8 +635,8 @@ xml:lang="en"> U - Unit (for example: System, CEC, Card Cage, Drawer, - Chassis (Unpopulated drawer)). + Unit (for example: System, CEC, Card Cage, Drawer, + Chassis (Unpopulated drawer)). . @@ -653,7 +653,7 @@ xml:lang="en"> W - Worldwide unique ID (for example: Fibre Channel). + Worldwide unique ID (for example: Fibre Channel). . @@ -662,7 +662,7 @@ xml:lang="en"> X - EIA value for empty rack location. See + EIA value for empty rack location. See . @@ -681,306 +681,306 @@ xml:lang="en">
Unit Location Label - The unit location label consists of the prefix “U” - followed by uppercase alphabetic characters, digits, and periods - (“.”). There is one and only one unit location label in a + The unit location label consists of the prefix “U” + followed by uppercase alphabetic characters, digits, and periods + (“.”). There is one and only one unit location label in a location code and it is the first element in the location code.
Planar Location Label - The planar location label consists of the prefix “P” - followed by a non-zero decimal number with no leading zeroes. Planar location - labels are present in location codes for planars and all locations on a planar. - There is at most one planar location label in a location code. When present, - the planar location label immediately follows the unit location label in the + The planar location label consists of the prefix “P” + followed by a non-zero decimal number with no leading zeroes. Planar location + labels are present in location codes for planars and all locations on a planar. + There is at most one planar location label in a location code. When present, + the planar location label immediately follows the unit location label in the location code. Planars are uniquely labeled within a unit.
Air Handler Location Label - An air handler location label consists of the prefix - “A” followed by a non-zero decimal number with no leading zeroes. - A location code may have zero or more air handler location labels. When - present, the air handler location label follows the location label of the + An air handler location label consists of the prefix + “A” followed by a non-zero decimal number with no leading zeroes. + A location code may have zero or more air handler location labels. When + present, the air handler location label follows the location label of the resource onto which the air handler is mounted, usually a unit or planar. Examples of air handlers include blowers and fans.
Card Connector Location Label - The card connector location label consists of the prefix - “C” followed by a non-zero decimal number with no leading zeroes. - A location code may contain zero or more card connector location labels. When - present, the card connector location label follows the location label of the - resource onto which the card is mounted, usually a planar or another + The card connector location label consists of the prefix + “C” followed by a non-zero decimal number with no leading zeroes. + A location code may contain zero or more card connector location labels. When + present, the card connector location label follows the location label of the + resource onto which the card is mounted, usually a planar or another card. - Examples of cards include: Plug-in I/O cards, processor cards, - daughter cards, DIMMs, regulator cards, MCMs, L3 cache modules, jumper cards, + Examples of cards include: Plug-in I/O cards, processor cards, + daughter cards, DIMMs, regulator cards, MCMs, L3 cache modules, jumper cards, pass-through interposers, and pluggable module chips.
Device Location Label - A device location label consists of the prefix “D” - followed by a non-zero decimal number with no leading zeroes. A location code - may have zero or more device location labels. When present, the device location - label follows the location label of the resource onto which the device is + A device location label consists of the prefix “D” + followed by a non-zero decimal number with no leading zeroes. A location code + may have zero or more device location labels. When present, the device location + label follows the location label of the resource onto which the device is mounted, usually a planar. - Device location labels are used for devices for which a physical - location can be determined. These are usually mounted in enclosures that have - rigid placement rules and, often, additional hardware support for location + Device location labels are used for devices for which a physical + location can be determined. These are usually mounted in enclosures that have + rigid placement rules and, often, additional hardware support for location determination, such as SES (Storage Enclosure Services) devices.
Electrical Location Label - An electrical location label consists of the prefix - “E” followed by a non-zero decimal number with no leading zeroes. - A location code may have zero or more electrical location labels. When present, - the electrical location label follows the location label of the resource onto + An electrical location label consists of the prefix + “E” followed by a non-zero decimal number with no leading zeroes. + A location code may have zero or more electrical location labels. When present, + the electrical location label follows the location label of the resource onto which the electrical resource is mounted, usually a unit or planar. - Examples of electrical resources include: batteries, power + Examples of electrical resources include: batteries, power supplies, and chargers.
Port Location Label - A port location label consists of the prefix “T” - followed by a non-zero decimal number with no leading zeroes. A location code - may have zero or more port location labels. When present, the port location - label follows the location label of the resource onto which the port is + A port location label consists of the prefix “T” + followed by a non-zero decimal number with no leading zeroes. A location code + may have zero or more port location labels. When present, the port location + label follows the location label of the resource onto which the port is mounted, usually a card or planar. - Examples of resources with a port location label include: ports, + Examples of resources with a port location label include: ports, connectors, cable connectors, jacks, and interposers.
Worldwide Unique Identifier - A worldwide unique identifier location label consists of the prefix - “W” followed by a maximum of 16 uppercase hexadecimal digits with - no leading zeroes. A location code may have zero or one worldwide unique - identifier location labels. When present, the worldwide unique identifier - location label follows the location label of the resource that interfaces with + A worldwide unique identifier location label consists of the prefix + “W” followed by a maximum of 16 uppercase hexadecimal digits with + no leading zeroes. A location code may have zero or one worldwide unique + identifier location labels. When present, the worldwide unique identifier + location label follows the location label of the resource that interfaces with the resource having the worldwide unique identifier, usually a port.
Logical Path Label - A logical path location label consists of the prefix - “L” followed by a decimal or hexadecimal number with no leading - zeros. Refer to through - to determine when decimal and hexadecimal - values are allowed. A location code may have zero or more logical path location - labels. When present, the logical path location label follows the location - label of the resource that interfaces with the resource being located, usually + A logical path location label consists of the prefix + “L” followed by a decimal or hexadecimal number with no leading + zeros. Refer to through + to determine when decimal and hexadecimal + values are allowed. A location code may have zero or more logical path location + labels. When present, the logical path location label follows the location + label of the resource that interfaces with the resource being located, usually a port or worldwide unique identifier. - The numeric value portion of the logical path label is a portion of - the address, appropriate to the protocol in use, which identifies the resource + The numeric value portion of the logical path label is a portion of + the address, appropriate to the protocol in use, which identifies the resource to be located.
Virtual Planar Location Label - A virtual planar label consists of the prefix “V” - followed by a non-zero decimal number with no leading zeroes. A location code - may have zero or one virtual planar location labels. When present, the virtual - planar location label will immediately follow the unit location label in a - location code. There is no physical label in the system or any I/O drawer + A virtual planar label consists of the prefix “V” + followed by a non-zero decimal number with no leading zeroes. A location code + may have zero or one virtual planar location labels. When present, the virtual + planar location label will immediately follow the unit location label in a + location code. There is no physical label in the system or any I/O drawer corresponding to the virtual planar location label. Virtual planars are uniquely labeled within a system.
Firmware Location Label - A firmware location label consists of the prefix “Y” - followed by a non-zero decimal number with no leading zeroes. A location code - may have zero or one firmware location labels. A firmware location code will - always contain a unit location label as its first element and a firmware + A firmware location label consists of the prefix “Y” + followed by a non-zero decimal number with no leading zeroes. A location code + may have zero or one firmware location labels. A firmware location code will + always contain a unit location label as its first element and a firmware location label its last element.
Horizontal Placement Location Label - The horizontal placement location label of an empty space in a rack - consists of the prefix “N” followed by a non-zero decimal number - with no leading zeroes. A location code may have zero or one horizontal - placement location labels. When present, the horizontal placement location + The horizontal placement location label of an empty space in a rack + consists of the prefix “N” followed by a non-zero decimal number + with no leading zeroes. A location code may have zero or one horizontal + placement location labels. When present, the horizontal placement location label immediately follows the EIA location label.
EIA Location Label - The EIA location label of an empty space in a rack consists of the - prefix “X” followed by a non-zero decimal number with no leading - zeroes. A location code may have zero or one EIA location labels. When present, + The EIA location label of an empty space in a rack consists of the + prefix “X” followed by a non-zero decimal number with no leading + zeroes. A location code may have zero or one EIA location labels. When present, the EIA location label immediately follows the frame location label.
Frame Location Label - The frame location label of an empty space in a rack consists of - the prefix “F” followed by a non-zero decimal number with no - leading zeroes. A location code may have zero or more frame location labels. - When present, the frame location label immediately follows the unit location + The frame location label of an empty space in a rack consists of + the prefix “F” followed by a non-zero decimal number with no + leading zeroes. A location code may have zero or more frame location labels. + When present, the frame location label immediately follows the unit location label.
Virtual Function Location Label - A virtual function label consists of the prefix “S” - followed by a zero-starting decimal number with no leading zeros. A location - code may have zero or more virtual function labels. When present, the virtual - function label is appended to the location code of the port that the virtual + A virtual function label consists of the prefix “S” + followed by a zero-starting decimal number with no leading zeros. A location + code may have zero or more virtual function labels. When present, the virtual + function label is appended to the location code of the port that the virtual function uses.
Mechanical Location Label - The Mechanical location label consists of the prefix - “M” followed by a nonzero decimal number with no leading zeroes. - A location code my have zero or more Mechanical location labels. When present, - the Mechanical location label follows the location label of the resource onto + The Mechanical location label consists of the prefix + “M” followed by a nonzero decimal number with no leading zeroes. + A location code my have zero or more Mechanical location labels. When present, + the Mechanical location label follows the location label of the resource onto which the mechanical device is mounted. - Examples of resources with a mechanical location label include: + Examples of resources with a mechanical location label include: plumbing, valves, and latches.
Resource Location Label - The Resource location label consists of the prefix - “R” followed by a nonzero decimal number with no leading zeroes. - A location code my have zero or more Resource location labels. When present, - the Resource location label follows the location label of the parent FRU. + The Resource location label consists of the prefix + “R” followed by a nonzero decimal number with no leading zeroes. + A location code my have zero or more Resource location labels. When present, + the Resource location label follows the location label of the parent FRU. - Resource location labels are resources, that are not FRUs, but that - need a location code label to be properly identified in the error log. An - example of a Resource is a module on the System backplane that is not a - separate FRU, but which needs to be separately identified in the system error + Resource location labels are resources, that are not FRUs, but that + need a location code label to be properly identified in the error log. An + example of a Resource is a module on the System backplane that is not a + separate FRU, but which needs to be separately identified in the system error log for a fail in place type of service strategy.
Converged Location Code Rules - This section describes the rules for building a location code. See - also the types of location code + This section describes the rules for building a location code. See + also the types of location code labels.
Usage of Location Codes - Any reference to a FRU must reference the official location + Any reference to a FRU must reference the official location code. - Unofficial internal forms or values of location codes which system - components may use for internal convenience are not to be presented to - customers, service personnel, etc. They are to be kept internal to those + Unofficial internal forms or values of location codes which system + components may use for internal convenience are not to be presented to + customers, service personnel, etc. They are to be kept internal to those components.
Persistence of Location Codes - Physical path location codes are permanent. Physical path location + Physical path location codes are permanent. Physical path location codes will not change unless there has been a change of hardware. - Logical path location codes are dependent on configuration - information and are therefore not permanent. Whenever reasonable and possible, - logical path location codes will persist across power cycles of the + Logical path location codes are dependent on configuration + information and are therefore not permanent. Whenever reasonable and possible, + logical path location codes will persist across power cycles of the system.
Forming Location Codes - Location codes are formed by concatenating one or more location - labels together. Location labels start at the largest or most general resource - (the unit) and proceed to the most specific in order of containment. The + Location codes are formed by concatenating one or more location + labels together. Location labels start at the largest or most general resource + (the unit) and proceed to the most specific in order of containment. The location labels are separated by dashes (“-”).
Length Restrictions - Location codes are no more than 79 characters in length. The + Location codes are no more than 79 characters in length. The lengths of individual location labels vary.
Location Labels Content - The unit location label may contain uppercase letters, digits, and - periods. All other location labels contain only upper case letters and digits. - This will avoid problems when printing or displaying the location codes on + The unit location label may contain uppercase letters, digits, and + periods. All other location labels contain only upper case letters and digits. + This will avoid problems when printing or displaying the location codes on double byte devices.
Physical Representation - In so far as it is possible, location labels must match the labels + In so far as it is possible, location labels must match the labels that are present on the hardware. - Generally, there are labels visible on the hardware to identify - connectors, slots, etc. These physical labels must adhere to this specification - and must be reflected in the corresponding location codes. This will eliminate - the need for the user to translate between the location code presented in logs, - displays, reports, and instructions and the location label found on the + Generally, there are labels visible on the hardware to identify + connectors, slots, etc. These physical labels must adhere to this specification + and must be reflected in the corresponding location codes. This will eliminate + the need for the user to translate between the location code presented in logs, + displays, reports, and instructions and the location label found on the hardware.
Multiple Function FRUs - Some FRUs (Field Replaceable Units) contain more than one logical - resource or function. The physical location code refers to the physical FRU. So - all the logical resources or functions on a FRU have the same physical location - code. Connectors on a FRU have different location codes except for the case of + Some FRUs (Field Replaceable Units) contain more than one logical + resource or function. The physical location code refers to the physical FRU. So + all the logical resources or functions on a FRU have the same physical location + code. Connectors on a FRU have different location codes except for the case of multiple connectors for one port.
Multiple Connectors for One Port - Some IOAs have multiple connectors (for example, a D-connector and - an RJ-45 connector) for one port. Since there is only one port involved, both + Some IOAs have multiple connectors (for example, a D-connector and + an RJ-45 connector) for one port. Since there is only one port involved, both connectors have the same location code.
Location Label Numbering Scope - For sequentially numbered location labels (planar, card, device, - air handler, electrical), each FRU has its own numbering space for its child - location labels. That numbering space begins with 1 and increments by 1 for - each child location label. Number is in decimal. For example, if there were two - planars in a unit, each planar having five card connectors, then each planar + For sequentially numbered location labels (planar, card, device, + air handler, electrical), each FRU has its own numbering space for its child + location labels. That numbering space begins with 1 and increments by 1 for + each child location label. Number is in decimal. For example, if there were two + planars in a unit, each planar having five card connectors, then each planar would show child location labels of C1, C2, C3, C4, and C5. - This means that for each parent, the child location labels begin - with a count of one. As a further example, if there were two adapters in - adjacent PCI slots each with two port connectors, the ports on the first - adapter would have location labels T1 and T2, and the ports on the second + This means that for each parent, the child location labels begin + with a count of one. As a further example, if there were two adapters in + adjacent PCI slots each with two port connectors, the ports on the first + adapter would have location labels T1 and T2, and the ports on the second adapter would have location labels of T1 and T2. - Note: Model-specific modifications to this - numbering rule may be made, when similar models of a product line are housed in - the same enclosure/rack, and the equivalent slots and connectors from each - model are lined up with each other as seen by the customer. Then the location - code numbering of these equivalent slots and connectors may be the same for - each model, even though numbers may be skipped or appear to be out of order on + Note: Model-specific modifications to this + numbering rule may be made, when similar models of a product line are housed in + the same enclosure/rack, and the equivalent slots and connectors from each + model are lined up with each other as seen by the customer. Then the location + code numbering of these equivalent slots and connectors may be the same for + each model, even though numbers may be skipped or appear to be out of order on specific models.
FRU Orientation - Locations are numbered left to right, top to bottom, back to front - with respect to the parent FRU, as viewed from the service position. However, a - location label does not change based on the orientation of a piece of hardware - within its parent hardware, for FRUs that may have more than one way of being + Locations are numbered left to right, top to bottom, back to front + with respect to the parent FRU, as viewed from the service position. However, a + location label does not change based on the orientation of a piece of hardware + within its parent hardware, for FRUs that may have more than one way of being oriented. - If a CEC or I/O drawer is used both in standalone and rack mounted - configurations, the rack mounted configuration takes precedence in determining + If a CEC or I/O drawer is used both in standalone and rack mounted + configurations, the rack mounted configuration takes precedence in determining location numbering.
Unit Location Codes - The unit location code is the unit location label, Un, for the - unit. The unit location label is permanent. The unit location labels may not be - etched on the containing racks, since it may not be possible to determine them + The unit location code is the unit location label, Un, for the + unit. The unit location label is permanent. The unit location labels may not be + etched on the containing racks, since it may not be possible to determine them during manufacture. - A system will have a unit location code composed of the machine - type, model, and serial number of the system with the components separated by - periods ('.'). For example, a system with machine type 9117, model 250, and + A system will have a unit location code composed of the machine + type, model, and serial number of the system with the components separated by + periods ('.'). For example, a system with machine type 9117, model 250, and serial number 10-ABCDE would have a location code of: @@ -989,16 +989,16 @@ xml:lang="en"> - Some I/O Drawers and CECs may be assigned machine type, model, and - serial numbers (MTMS) by manufacturing. Other I/O Drawers and CECs may be - assigned feature code, count, and serial numbers by manufacturing. The same - requirements for uniqueness apply to both identification schemes. The data is - formatted in exactly the same way. And, for the purposes of location codes, the + Some I/O Drawers and CECs may be assigned machine type, model, and + serial numbers (MTMS) by manufacturing. Other I/O Drawers and CECs may be + assigned feature code, count, and serial numbers by manufacturing. The same + requirements for uniqueness apply to both identification schemes. The data is + formatted in exactly the same way. And, for the purposes of location codes, the data will be used in exactly the same way. - Drawers and CECs which have a machine type, model, and serial - number which the system can obtain will have a unit location code composed of - the machine type, model, and serial number with the components separated by - periods (“.”). For example, a drawer with machine type 5703, + Drawers and CECs which have a machine type, model, and serial + number which the system can obtain will have a unit location code composed of + the machine type, model, and serial number with the components separated by + periods (“.”). For example, a drawer with machine type 5703, model 012, and serial number 10-30490 would have a location code of: @@ -1007,11 +1007,11 @@ xml:lang="en"> - Drawers and CECs which have a feature code, count, and serial - number which the system can obtain will have a unit location code composed of - the feature code, count, and serial number with the components separated by - periods (‘.’), for readability. For example, a drawer with - feature code 0573, count 001, and serial number 10-40320 would have a location + Drawers and CECs which have a feature code, count, and serial + number which the system can obtain will have a unit location code composed of + the feature code, count, and serial number with the components separated by + periods (‘.’), for readability. For example, a drawer with + feature code 0573, count 001, and serial number 10-40320 would have a location code of: @@ -1020,77 +1020,77 @@ xml:lang="en"> - Additionally, the count portion of the location code unit label may - be modified by firmware at boot time to reflect information about the physical - location. It may be modified according to whatever scheme appropriate for the - unit's configuration -- provided all other location code rules are followed and - that the scheme generates the same value every time when no actual or relative - physical location change has been made. For example, TUn (“TU” to - indicate the Top CEC Unit, n=1,2,3, or 4 to indicate which drawer numbered top - to bottom) may be substituted for the actual count value, so an imaginary CEC + Additionally, the count portion of the location code unit label may + be modified by firmware at boot time to reflect information about the physical + location. It may be modified according to whatever scheme appropriate for the + unit's configuration -- provided all other location code rules are followed and + that the scheme generates the same value every time when no actual or relative + physical location change has been made. For example, TUn (“TU” to + indicate the Top CEC Unit, n=1,2,3, or 4 to indicate which drawer numbered top + to bottom) may be substituted for the actual count value, so an imaginary CEC following this scheme might have a unit label of: U1234.TU1.5678901 - Enclosure feature code/count must never collide with one another or - with any machine type/model. Likewise, enclosure machine type/model must never + Enclosure feature code/count must never collide with one another or + with any machine type/model. Likewise, enclosure machine type/model must never collide with one another or any enclosure feature code/count. - Drawers for which the system cannot obtain a machine type, model, - and serial or a feature code, count, and serial number, will have a location - code of the form Uttaa. In this form, the tt is an alphabetic string - identifying the kind of drawer, for example, SSA. The aa is a string provided - by the rules of the OS to identify the instance of the drawer within the - particular system. For example: USSABKUP. The lengths of both tt and aa will - vary depending on the kind of drawer. The OS must provide mechanisms by which + Drawers for which the system cannot obtain a machine type, model, + and serial or a feature code, count, and serial number, will have a location + code of the form Uttaa. In this form, the tt is an alphabetic string + identifying the kind of drawer, for example, SSA. The aa is a string provided + by the rules of the OS to identify the instance of the drawer within the + particular system. For example: USSABKUP. The lengths of both tt and aa will + vary depending on the kind of drawer. The OS must provide mechanisms by which the customer can ensure the uniqueness of these values.
Planar Location Codes - Planar location codes are formed by appending the planar location - label, Pn, to the location code of the unit that contains the planar. The Pn - value is assigned during the engineering design and manufacturing process, is - unique within the unit, is physically displayed on the parent resource, and is - present in the VPD of the parent resource. This process is the same + Planar location codes are formed by appending the planar location + label, Pn, to the location code of the unit that contains the planar. The Pn + value is assigned during the engineering design and manufacturing process, is + unique within the unit, is physically displayed on the parent resource, and is + present in the VPD of the parent resource. This process is the same irrespective of the kind of planar involved. - Note: In some implementations, a planar is - not a separate FRU but is considered to be part of the enclosure. For - consistency of the user interface, the enclosure in these cases is still - considered to have a location code consisting entirely of a unit location - label. In these cases, the planar has a location code consisting of both the - unit location label and the planar location label. This is done even though the - planar is not a separate FRU. In these cases, service related VPD and errors + Note: In some implementations, a planar is + not a separate FRU but is considered to be part of the enclosure. For + consistency of the user interface, the enclosure in these cases is still + considered to have a location code consisting entirely of a unit location + label. In these cases, the planar has a location code consisting of both the + unit location label and the planar location label. This is done even though the + planar is not a separate FRU. In these cases, service related VPD and errors will be reported with the planar location code.
Card Connector Location Codes - Card connector location codes are formed by appending the card - connector location label, Cn, to the location code of the resource to which the - card is docked. The location label, Cn, assigned in the engineering and - manufacturing process, is unique within the parent resource, is physically - displayed on the parent resource, and is present in the VPD of the parent + Card connector location codes are formed by appending the card + connector location label, Cn, to the location code of the resource to which the + card is docked. The location label, Cn, assigned in the engineering and + manufacturing process, is unique within the parent resource, is physically + displayed on the parent resource, and is present in the VPD of the parent resource. - The process is the same irrespective of the kind of card + The process is the same irrespective of the kind of card involved.
Riser Card Connector Location Codes - Riser card connector location codes are formed by appending the - card location label, Cn, of the child card to the location code of the parent + Riser card connector location codes are formed by appending the + card location label, Cn, of the child card to the location code of the parent card to which it is attached. For example: U5702.115.1031010-P3-C4-C2
Blade Daughter Card Connector Location Codes - The Blade daughter card slot can actually contain multiple - partitionable endpoints depending on the type of daughter card attached. The - PCI-E bus can be split (bifurcated) between two PHB's that are separately - DLPAR-able (just not hot-pluggable) resources. When that occurs, a -L# suffix - is required after the -C# of the daughter card slot to distinctly identify - between the two PE's. For example, when the daughter card contains two 4x PCIE + The Blade daughter card slot can actually contain multiple + partitionable endpoints depending on the type of daughter card attached. The + PCI-E bus can be split (bifurcated) between two PHB's that are separately + DLPAR-able (just not hot-pluggable) resources. When that occurs, a -L# suffix + is required after the -C# of the daughter card slot to distinctly identify + between the two PE's. For example, when the daughter card contains two 4x PCIE devices, the location code for the two PE's might be: @@ -1100,8 +1100,8 @@ xml:lang="en"> U78A0.001.DNWGDG0-P1-C10-L2 - The actual daughter card device ports, in this example, will have - the -T# suffix (starting from 1) on top of those. For example, a 4-port PCI-E + The actual daughter card device ports, in this example, will have + the -T# suffix (starting from 1) on top of those. For example, a 4-port PCI-E Ethernet daughter card, might have location codes like: @@ -1117,29 +1117,29 @@ xml:lang="en"> U78A0.001.DNWGDG0-P1-C10-L2-T2 - If only a single PCI device is on the daughter card, then the -L# - suffix should not be used, as the -C# is sufficient to identify the PE and + If only a single PCI device is on the daughter card, then the -L# + suffix should not be used, as the -C# is sufficient to identify the PE and device.
Virtual Card Connector Location Codes - Virtual card connector location codes are formed as + Virtual card connector location codes are formed as though there were a virtual planar with card slots. - For example, the location code for a virtual IOA in partition + For example, the location code for a virtual IOA in partition 5 and in virtual slot 3 would be of the form: U9117.001.1076DEF-V5-C4 - The partition number 5 is specified in the V label + The partition number 5 is specified in the V label and the virtual slot number 3 is specified in the C - label. Also note that the U label specifies the system + label. Also note that the U label specifies the system type, model, and serial (the system location code), not the enclosure type, model, and serial. - - Some operating systems may append a T label + + Some operating systems may append a T label to the virtual IOA location code. For example: @@ -1147,103 +1147,103 @@ xml:lang="en">
- +
Port Location Codes - Port location codes are formed by appending the port location - label, Tn, to the location code of the resource on which the port connector is - mounted. The location label, Tn, assigned in the engineering and manufacturing - process, is unique within the parent resource, is physically displayed on the + Port location codes are formed by appending the port location + label, Tn, to the location code of the resource on which the port connector is + mounted. The location label, Tn, assigned in the engineering and manufacturing + process, is unique within the parent resource, is physically displayed on the parent resource, and is present in the VPD of the parent resource.
Resources without Port VPD - If a resource without slot map VPD has port numbers physically - marked on it, the hard coded slot map will reflect the marked numbers and - letters with a “T” prefix. Any letters will be folded to - uppercase to avoid double byte display concerns. (Note: only letters 'A' - 'F' - may be used in a port location label. Other letters on the card will be ignored - and numbers will be assigned for uniqueness.) It is recognized that location - labels formed in this way may not conform to the location label rules stated in + If a resource without slot map VPD has port numbers physically + marked on it, the hard coded slot map will reflect the marked numbers and + letters with a “T” prefix. Any letters will be folded to + uppercase to avoid double byte display concerns. (Note: only letters 'A' - 'F' + may be used in a port location label. Other letters on the card will be ignored + and numbers will be assigned for uniqueness.) It is recognized that location + labels formed in this way may not conform to the location label rules stated in . - If the port labels are not marked on the standalone adapter, the - hard coded slot map will specify location labels of Tn, where n is decimal and - equal to the port address (i.e. port 0 will map to T1, port 1 will map to T2, - etc.) Whenever possible, the hardware design should be such that this will lead - to the preferred left to right, top to bottom, front to back ordering. For - standalone adapters that can be installed in multiple systems, ports are - labeled beginning with the PCI connector and continuing toward the opposite - edge of the card and from tailstock forward toward the opposite edge of the + If the port labels are not marked on the standalone adapter, the + hard coded slot map will specify location labels of Tn, where n is decimal and + equal to the port address (i.e. port 0 will map to T1, port 1 will map to T2, + etc.) Whenever possible, the hardware design should be such that this will lead + to the preferred left to right, top to bottom, front to back ordering. For + standalone adapters that can be installed in multiple systems, ports are + labeled beginning with the PCI connector and continuing toward the opposite + edge of the card and from tailstock forward toward the opposite edge of the card. - If the adapter is imbedded on a FRU which does not have port - location labels marked on it and has ports for other functions, then the - numbering to the ports in the hard coded slot map must take into account the - other ports on the FRU. The hard coded slot map will comply with the left to - right, bottom to top, front to back ordering guidelines. In this case, the - first port for the imbedded adapter may be other than T0 and may not be + If the adapter is imbedded on a FRU which does not have port + location labels marked on it and has ports for other functions, then the + numbering to the ports in the hard coded slot map must take into account the + other ports on the FRU. The hard coded slot map will comply with the left to + right, bottom to top, front to back ordering guidelines. In this case, the + first port for the imbedded adapter may be other than T0 and may not be contiguous.
Determining Port Number - If the port number cannot be determined from VPD or VPD plus - configuration or addressing information, software or firmware must infer the + If the port number cannot be determined from VPD or VPD plus + configuration or addressing information, software or firmware must infer the port number. - + - For SCSI IOAs with multiple PCI configuration spaces, each port + For SCSI IOAs with multiple PCI configuration spaces, each port has its own configuration space. - + - For multiport SCSI IOAs with a single PCI configuration space, - firmware or software will add n+1 to the base port's distinguishing value to - obtain the port number for the nth port. Thus port 0 (usually closest to the - PCI connector edge of the card) will have label T1, port 1 will have label T2, + For multiport SCSI IOAs with a single PCI configuration space, + firmware or software will add n+1 to the base port's distinguishing value to + obtain the port number for the nth port. Thus port 0 (usually closest to the + PCI connector edge of the card) will have label T1, port 1 will have label T2, etc. - +
Physical Device Location Codes - Devices whose parent supports location label - VPDSES devices on SCSI backplanes contain VPD that has - a slot map. The slot map associates a SCSI LUN with a location label. Some - backplanes that do not actually have SES support have a virtual SES that - provides the same function. It is assumed that future protocols will support - equivalent function. - (that is, mounted/docked on a backplane - that supports location information for docked devices) will have physical + Devices whose parent supports location label + VPDSES devices on SCSI backplanes contain VPD that has + a slot map. The slot map associates a SCSI LUN with a location label. Some + backplanes that do not actually have SES support have a virtual SES that + provides the same function. It is assumed that future protocols will support + equivalent function. + (that is, mounted/docked on a backplane + that supports location information for docked devices) will have physical location codes. For example, - + U5734.001.10ABCDE-P3-D19 - Physical device location codes are formed by appending the physical - device location label, Dn, to the location code of the resource to which the - device is docked. The location label, Dn, assigned in the engineering and - manufacturing process, is unique within the parent resource, is physically - displayed on the parent resource, and is present in the VPD of the parent + Physical device location codes are formed by appending the physical + device location label, Dn, to the location code of the resource to which the + device is docked. The location label, Dn, assigned in the engineering and + manufacturing process, is unique within the parent resource, is physically + displayed on the parent resource, and is present in the VPD of the parent resource. Notes: - + - AIX will use logical path location codes for SCSI devices even - in situations where a SES device is available to provide device location label + AIX will use logical path location codes for SCSI devices even + in situations where a SES device is available to provide device location label information. - In some cases, a location code may need to be displayed or - logged before the information from the backplane is available to form the - physical location code. In these cases, a logical path location code will be - formed according to the applicable rules and used temporarily. Once the - information needed to form the physical device label is available, the physical + In some cases, a location code may need to be displayed or + logged before the information from the backplane is available to form the + physical location code. In these cases, a logical path location code will be + formed according to the applicable rules and used temporarily. Once the + information needed to form the physical device label is available, the physical device location code will be used. @@ -1252,13 +1252,13 @@ xml:lang="en">
SCSI Device Logical Path Location Codes -- Real - SCSI (Small Computer System Interface) devices whose parent does - not support location label VPD will have location codes that are composed of - the location code of the controlling SCSI port followed by the SCSI Target - (0-15) and SCSI LUN (Logical Unit Number). A SCSI logical-path example + SCSI (Small Computer System Interface) devices whose parent does + not support location label VPD will have location codes that are composed of + the location code of the controlling SCSI port followed by the SCSI Target + (0-15) and SCSI LUN (Logical Unit Number). A SCSI logical-path example is: - + U7043.150.1076543-P4-T3-L13-L0 (Decimal L values) @@ -1268,14 +1268,14 @@ xml:lang="en">
SAS Device Logical Path Location Codes - SAS (Serial SCSI) devices whose parent FRU does not support - location label VPD will have location codes that are composed of the location - code of the controlling SAS adapter followed by a series of port labels, - “-L#”, for each SAS port traversed from the adapter down to the - drive followed by the SCSI LUN (Logical Unit Number). The number value of the - “-L#” label will be the lowest phy in the outgoing SAS port with + SAS (Serial SCSI) devices whose parent FRU does not support + location label VPD will have location codes that are composed of the location + code of the controlling SAS adapter followed by a series of port labels, + “-L#”, for each SAS port traversed from the adapter down to the + drive followed by the SCSI LUN (Logical Unit Number). The number value of the + “-L#” label will be the lowest phy in the outgoing SAS port with # being a decimal value. For example: - + U7043.150.1076543-P1-C3-L3-L1-L5-L0 @@ -1284,19 +1284,19 @@ xml:lang="en">
IDE/ATAPI Device Logical Path Location Codes - The desired form of the location code is based on the physical-path + The desired form of the location code is based on the physical-path location codes obtained from VPD. For example: - + U5734.001.1076543-P2-D4 - For an IDE device that had an older form of VPD (without physical + For an IDE device that had an older form of VPD (without physical location codes), then its location code would have looked like: - + Ux-Px-(Cx)-Tx-L# (from -L0 to -L3 where: @@ -1309,16 +1309,16 @@ xml:lang="en">
- Fibre Channel Device Logical Path Location Codes -- + <title>Fibre Channel Device Logical Path Location Codes -- Real - Fibre channel devices that are not mounted/docked on a backplane - that supports location code VPD will have location codes composed of the - location of the port on the controlling IOA followed by the worldwide unique - port identifier and LUN. The number value (#) of the “-L#” label - is a hexadecimal value. An example FC disk attached to a physical adapter + Fibre channel devices that are not mounted/docked on a backplane + that supports location code VPD will have location codes composed of the + location of the port on the controlling IOA followed by the worldwide unique + port identifier and LUN. The number value (#) of the “-L#” label + is a hexadecimal value. An example FC disk attached to a physical adapter is: - - + + U787A.001.1012345-P1-C5-T2-W123456789ABCDEF0-L1A05000000000000 @@ -1326,19 +1326,19 @@ xml:lang="en">
- Location Codes for SR-IOV Adapter Virtual + <title>Location Codes for SR-IOV Adapter Virtual Functions - Single Root IO Virtualization allows for multiple “virtual - functions” to share the same physical port of a PCI adapter. The -S# - suffix, appended to the physical location code of the port (-T#), is used to - identify the unique virtual function using that port. The number value (#) of - the “-S#” label is a zero starting decimal value determined and - managed by the software layer that owns the physical functions of the SR-IOV + Single Root IO Virtualization allows for multiple “virtual + functions” to share the same physical port of a PCI adapter. The -S# + suffix, appended to the physical location code of the port (-T#), is used to + identify the unique virtual function using that port. The number value (#) of + the “-S#” label is a zero starting decimal value determined and + managed by the software layer that owns the physical functions of the SR-IOV adapter. - For an SR-IOV ethernet adapter, the third virtual function for the + For an SR-IOV ethernet adapter, the third virtual function for the first ethernet port would look like: - + U7043.150.1076543-P1-C5-T1-S2 @@ -1347,68 +1347,68 @@ xml:lang="en">
Group Labels - Group labels appear on parent FRUs to indicate groupings such as - port or DIMM pairs. Group labels are not part of the location label or location - code. Group labels may be part of slot map VPD and may be processed by software + Group labels appear on parent FRUs to indicate groupings such as + port or DIMM pairs. Group labels are not part of the location label or location + code. Group labels may be part of slot map VPD and may be processed by software that displays information on the corresponding FRUs.
Sandwich FRU Location Label - A Sandwich FRU has a single location label to describe its location + A Sandwich FRU has a single location label to describe its location just as any single FRU would.
Sandwich FRU Child Location Labels - A Sandwich FRU is like any single FRU in that it has one numbering + A Sandwich FRU is like any single FRU in that it has one numbering space for numbering its child locations.
Location Code Reported by Sensors - The location code reported by a sensor is the location code of the + The location code reported by a sensor is the location code of the FRU being monitored by the sensor.
Sensor Locations - The location code of a sensor is the location code of the FRU on + The location code of a sensor is the location code of the FRU on which the sensor is located.
Location Code Reported for Indicators - The VPD that reports an indicator will give the location label of - the resource identified by the indicator, not the location label of the + The VPD that reports an indicator will give the location label of + the resource identified by the indicator, not the location label of the indicator itself.
Indicator Locations - The location code of an indicator is the location code of the FRU + The location code of an indicator is the location code of the FRU on which the indicator is located.
Firmware Location Codes - The location specified for firmware is left to the platform except - that the location code must match the scope of the firmware and the location - code must follow the form specified above, beginning with a unit location label - and ending with a firmware location label. For example, firmware for port 2 (T + The location specified for firmware is left to the platform except + that the location code must match the scope of the firmware and the location + code must follow the form specified above, beginning with a unit location label + and ending with a firmware location label. For example, firmware for port 2 (T location label value) on planar 1 could have a location code of the form: - + U7879.001.1054321-P1-Y2 - If the firmware is considered to be system wide, then the planar - location label would not be present and the unit location label specifies the + If the firmware is considered to be system wide, then the planar + location label would not be present and the unit location label specifies the system location code not the CEC enclosure location code: - + U9117.001.1054321-Y1 @@ -1417,126 +1417,126 @@ xml:lang="en">
Bulk Power Assembly (BPA) Location Codes - The unit location label for a BPA and its components consists of - the “U” prefix and the MTMS of the rack of which the BPA is a + The unit location label for a BPA and its components consists of + the “U” prefix and the MTMS of the rack of which the BPA is a component. - In some configurations, there are two BPAs in one rack. If they - were treated separately, the second BPA would have the same location label as - the first which would lead to location code collisions. Therefore, from the - perspective of location codes, the two BPAs will be treated as on BPA. The - planar location labels and, when necessary, other location labels within the - second BPA are incremented so that they are not the same as the labels in the - first BPA. For example, the front side BPA has a planar P1 and the back side + In some configurations, there are two BPAs in one rack. If they + were treated separately, the second BPA would have the same location label as + the first which would lead to location code collisions. Therefore, from the + perspective of location codes, the two BPAs will be treated as on BPA. The + planar location labels and, when necessary, other location labels within the + second BPA are incremented so that they are not the same as the labels in the + first BPA. For example, the front side BPA has a planar P1 and the back side BPA has a planar P2 etc.
Internal Battery Features Location Codes - The unit location label of an Internal Battery Feature (IBF) is the - unit location label of the BPA to which it belongs. The planar location labels - and, if necessary, other location labels within the IBF are incremented so that - they are not the same as the labels in the BPA or any other IBF belonging to + The unit location label of an Internal Battery Feature (IBF) is the + unit location label of the BPA to which it belongs. The planar location labels + and, if necessary, other location labels within the IBF are incremented so that + they are not the same as the labels in the BPA or any other IBF belonging to that BPA.
Media Drawer Location Codes - In some configurations, there are media drawers that do not have a - MTMS. The unit location label for these media drawers is the unit location - label of the CEC to which it belongs. The planar location labels and, if - necessary, other location labels within the media are incremented so that they - are not the same as the labels in any other media drawer in the system or any + In some configurations, there are media drawers that do not have a + MTMS. The unit location label for these media drawers is the unit location + label of the CEC to which it belongs. The planar location labels and, if + necessary, other location labels within the media are incremented so that they + are not the same as the labels in any other media drawer in the system or any labels in the CEC.
Horizontal Placement Location Labels - The horizontal placement location label begins with the prefix - “N” followed by the digit “1” for the left side of - the frame (viewed from the front) or the digit “2” for the right + The horizontal placement location label begins with the prefix + “N” followed by the digit “1” for the left side of + the frame (viewed from the front) or the digit “2” for the right side of the frame (when viewed from the front).
EIA Location Label - The EIA location label begins with the prefix “X” - followed by a nonzero digit which represents the EIA location of the bottom of + The EIA location label begins with the prefix “X” + followed by a nonzero digit which represents the EIA location of the bottom of the unit that is or would be in the frame at that location.
Blade Chassis Location Codes - The disk storage module in a blade chassis may consist of a - backplane and a set of disks that plug into the backplane. Such a storage - module is assigned an enclosure feature code which is used to define the unit + The disk storage module in a blade chassis may consist of a + backplane and a set of disks that plug into the backplane. Such a storage + module is assigned an enclosure feature code which is used to define the unit location label (Un) of a disk in a storage module. - In some blade chassis there may be multiple identical storage - modules. All storage modules have a unit location with the same enclosure - feature code. The backplane within the left storage module has label P1, the - backplane in the next storage enclosure has label P2, and so on, to help with + In some blade chassis there may be multiple identical storage + modules. All storage modules have a unit location with the same enclosure + feature code. The backplane within the left storage module has label P1, the + backplane in the next storage enclosure has label P2, and so on, to help with disk identification.
Location Codes for Hot-pluggable Devices - There are multiple occasions where devices may be added after the - system has booted and the addition did not use any dynamic reconfiguration - flows. In this situation, the O/S does not have adequate information from the - device tree's “ibm,loc-code” properties to - construct a correct physical location code. One example of this is with - IDE/SCSI drives that are hot-pluggable, where the O/S only knows the logical - location code from the IDE/SCSI bus. Firmware, however, may know the physical - location code of the drive based on the unit-address. Similarly, a USB root-hub - may have multiple down-facing ports with different physical location codes, but - the root-hub is only a single device tree node, so only a single location code + There are multiple occasions where devices may be added after the + system has booted and the addition did not use any dynamic reconfiguration + flows. In this situation, the O/S does not have adequate information from the + device tree's “ibm,loc-code” properties to + construct a correct physical location code. One example of this is with + IDE/SCSI drives that are hot-pluggable, where the O/S only knows the logical + location code from the IDE/SCSI bus. Firmware, however, may know the physical + location code of the drive based on the unit-address. Similarly, a USB root-hub + may have multiple down-facing ports with different physical location codes, but + the root-hub is only a single device tree node, so only a single location code can be provided with just the “ibm,loc-code” property. - The “ibm,loc-code-map” property - contains a list of pairs (unit-address, location code), both as encoded - strings. It describes the physical location code for each potential child + The “ibm,loc-code-map” property + contains a list of pairs (unit-address, location code), both as encoded + strings. It describes the physical location code for each potential child node. - R1-R1--1. - The instance of each USB root-hub in - the device tree must contain the “ibm,loc-code-map” property if the root-hub has multiple down-facing ports. This - applies to both the OHCI and EHCI interfaces of a USB adapter. Lack of this - property implies there is only a single down-facing root-hub port from that USB + The instance of each USB root-hub in + the device tree must contain the “ibm,loc-code-map” property if the root-hub has multiple down-facing ports. This + applies to both the OHCI and EHCI interfaces of a USB adapter. Lack of this + property implies there is only a single down-facing root-hub port from that USB interface. - + - R1-R1--2. - To determine the location code for an - end device associated with leaf open firmware node, the O/S must use the - “ibm,loc-code-map” entry with a matching - unit-address, if it exists, in preference to the parent's + To determine the location code for an + end device associated with leaf open firmware node, the O/S must use the + “ibm,loc-code-map” entry with a matching + unit-address, if it exists, in preference to the parent's “ibm,loc-code” property. - + - R1-R1--3. - The “ibm,loc-code-map” property must not contain an entry - for a port from an embedded IOA that is not externally connected, or if the + The “ibm,loc-code-map” property must not contain an entry + for a port from an embedded IOA that is not externally connected, or if the location code is undeterminable. - + - R1-R1--4. - If the unit-address architecture for - certain node types do not strictly bind a particular unit-address with a - hardware location, the “ibm,loc-code-map” + If the unit-address architecture for + certain node types do not strictly bind a particular unit-address with a + hardware location, the “ibm,loc-code-map” property must not exist in the parent of those nodes. @@ -1545,190 +1545,221 @@ xml:lang="en">
Location Code for USB Attached Devices - The root hub port number used determines the location code up to - the Tn suffix. There can be zero or many intervening hubs, and the intervening - “Ln” location labels are in path order. All immediate children - are of root hubs are represented by “L1”. For devices not - directly attached to the root hub, the “Ln” will correspond to - the software port number, n, of the parent hub that a device is attached to, + The root hub port number used determines the location code up to + the Tn suffix. There can be zero or many intervening hubs, and the intervening + “Ln” location labels are in path order. All immediate children + are of root hubs are represented by “L1”. For devices not + directly attached to the root hub, the “Ln” will correspond to + the software port number, n, of the parent hub that a device is attached to, counting from 1. - For example, the location code for a USB device attached to an IOA - imbedded on a backplane with location label P1, using port T5, and with an - intervening hub under which the device is attached to the third port would + For example, the location code for a USB device attached to an IOA + imbedded on a backplane with location label P1, using port T5, and with an + intervening hub under which the device is attached to the third port would be: - + U787A.001.10ABCDE-P1-T5-L1-L3
+ +
+ Location Code for Coherent Platform Facility + + A Coherent Platform Facility serves as the parent node for Coherent + Platform Function devices. These devices describe the virtual topology of + the coherently attached function. The location code is derived from the + physical resource loca- tion code that the coherent platform facility is + representing. For example, the form of the location code is: + + + + U1234.001.1054321-P1-C7 + + +
+ +
+ Location Code for Coherent Platform Function + A Coherent Platform Function comprises a coherently attached functional + unit. These location codes are formed by ap- pending a -Sy-Sz label which + is a zero starting decimal value that describes the resources within the + Coherent Platform Facility that are used by the Coherent Platform Function. + For example, the form of the location code is: + + + + U1234.001.1054321-P1-C7-S0-S1 + + +
- +
Resource Location Codes - - The resource location label consists of the + + The resource location label consists of the prefix 'R' followed by a non-zero decimal number. A - resource location code identifies a chip or function + resource location code identifies a chip or function embedded on a FRU. There may be multiple - resources associated with a FRU. The numbering of the + resources associated with a FRU. The numbering of the resources on a particular FRU should match the left to right, top to bottom positioning of the resources on the FRU when the FRU is in a typical service position. - - It should be noted that embedded adapters with + + It should be noted that embedded adapters with internal ports existed prior to introduction of the - resource label. Use of the resource label for unique + resource label. Use of the resource label for unique partitionable endpoint identification may or may - not be retrofitted to those adapters as they are + not be retrofitted to those adapters as they are carried forward to new platforms.
- +
Multiple FRUs In The Same Physical Space - - A physical location code is tied to the connector + + A physical location code is tied to the connector that a FRU plugs into. If two different parts with - different part numbers can plug into the same connector, + different part numbers can plug into the same connector, both parts will have the same location code. - However, if two different parts can plug into two + However, if two different parts can plug into two different connectors but share the same physical - space when either is installed, those parts should + space when either is installed, those parts should each have a different location code. For example, if - two different GX adapters (such as the Bjorn IB adapter + two different GX adapters (such as the Bjorn IB adapter and Newcombe PCI slot riser on Jupiter-IOC) - connect to the same planar using the same connector, + connect to the same planar using the same connector, they should both be assigned the same location - code. But if a GX adapter or a PCI adapter can be + code. But if a GX adapter or a PCI adapter can be installed on a planar, but not both at the same time - as they both can't fit at the same time given the + as they both can't fit at the same time given the placement of the connectors on the planar, both slots should be assigned unique location codes.
- +
PCI-E Attached I/O Drawers - - A PCI-E attached I/O drawer is an I/O drawer that + + A PCI-E attached I/O drawer is an I/O drawer that attaches to a GX adapter in the CEC via PCI-E - cables (as opposed to RIO or IB cables). There are two + cables (as opposed to RIO or IB cables). There are two different types of PCI-E attached I/O drawers: - ones where PHB(s) on the GX adapter connect directly + ones where PHB(s) on the GX adapter connect directly to I/O devices in the drawer and ones where the - PHB(s) on the GX adapter connect to switches (or other + PHB(s) on the GX adapter connect to switches (or other fan-out logic) in the I/O drawer. In the former - case, the partitionable endpoint (PE) is the logical + case, the partitionable endpoint (PE) is the logical PHB connection to the device. In the latter case, the PEs are the slots wired to the downstream switch ports. - For GX cards whose PHBs connect directly to + For GX cards whose PHBs connect directly to devices in the I/O drawer (such as Bluehawk), the - location code and DRC name of the I/O slot partitionable + location code and DRC name of the I/O slot partitionable endpoint will be of the form Ucec-Pw-Cx- - Ty-Lz. Here, Ucec is the type/model/serial of the CEC + Ty-Lz. Here, Ucec is the type/model/serial of the CEC that contains the GX adapter, Pw is the planar - that contains the GX adapter, Cx is the GX adapter, + that contains the GX adapter, Cx is the GX adapter, Ty is one of the ports on the adapter, and Lz is a - logical label representing a logical PCI-e connection + logical label representing a logical PCI-e connection to an I/O device at the other end of the PCI-e - cable plugged into that port (note that there may be + cable plugged into that port (note that there may be multiple Cx labels if the GX adapter doesn't plug - directly into the planar in the system in question). + directly into the planar in the system in question). This location code and DRC name will be generated - by system firmware for each PE on each GX adapter that + by system firmware for each PE on each GX adapter that is installed in the system and that supports - direct-connect drawers (i.e. drawers without a PCI-E + direct-connect drawers (i.e. drawers without a PCI-E switch in them). The location code and DRC - name will be generated regardless of whether or not a + name will be generated regardless of whether or not a PCI-E cable is attached to the GX adapter. - It is permissible to append additional labels beyond + It is permissible to append additional labels beyond the L label to create different location codes for - FRUs/devices downstream from the I/O device in the + FRUs/devices downstream from the I/O device in the drawer that is attached to the PCI-e cable. It is not required that all subsequent labels be logical labels. - For GX cards whose ports connect to a PCI-E switch + For GX cards whose ports connect to a PCI-E switch in an I/O drawer via PCI-E cables, the location code format has not yet been defined.
- +
Virtual SCSI (vSCSI) Device Location Codes - - The location code for a virtual SCSI (vSCSI) + + The location code for a virtual SCSI (vSCSI) device is formed by appending an L label to the location - code of the parent virtual IOA. The L label contains a + code of the parent virtual IOA. The L label contains a 48 or 64 bit hexadecimal value that uniquely - identifies the virtualized SCSI device. A virtual + identifies the virtualized SCSI device. A virtual SCSI device attached to a virtual IOA at U9119.MME.1085B17-V4-C5-T1 would have a location code of the form: U9119.MME.1085B17-V4-C5-T1-L8100000000000000 - Note that some old pSeries firmware may represent + Note that some old pSeries firmware may represent the virtualized device identifier as W8100000000000000-L0 rather than simply L8100000000000000. This approach was abandoned in late 2008. - - See for a description of the + + See for a description of the virtual IOA location code.
- +
Virtual Fibre Channel Device Location Codes - - The location code for a virtual fibre channel device + + The location code for a virtual fibre channel device is formed by appending the worldwide unique port - identifier (W label) and LUN (L label) to the location + identifier (W label) and LUN (L label) to the location code of the parent virtual IOA. The values of - the L and W labels are both in hexadecimal. A fibre + the L and W labels are both in hexadecimal. A fibre channel disk attached to a virtual IOA at - U9119.MME.1085B17-V4-C5-T1 would have a location + U9119.MME.1085B17-V4-C5-T1 would have a location code of the form: - + U9119.MME.1085B17-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000 - - See for a description of the + + See for a description of the virtual IOA location code.
- +
NVMe Device Logical Path Location Codes - - Non-volatile memory (NVM) devices that are + + Non-volatile memory (NVM) devices that are not mounted/docked on a backplane that supports - location code VPD will have location codes composed + location code VPD will have location codes composed of the location code of the controlling IOA - followed by a L label. The number value of L label + followed by a L label. The number value of L label is a decimal value, and it is the unique NVMe - namespace identifier. An NVMe device controlled by + namespace identifier. An NVMe device controlled by an IOA at U787A.001.1012345-P1-C5 would have a location code of the form: - + U787A.001.1012345-P1-C5-L3
- +
Virtual Coherent Accelerator (CAPI) Function Location Codes - - The location code for a virtual coherent accelerator + + The location code for a virtual coherent accelerator (CA) function is formed by appending two S labels, - the first specifying the identifier of the physical + the first specifying the identifier of the physical function and the second specifying the identifier of the - logical function, both in decimal, to the location code of + logical function, both in decimal, to the location code of the physical CAPI adapter. A virtual CA - function associated with physical function 1 and logical + function associated with physical function 1 and logical function 2 on the CAPI adapter at location U78CA.001.1234567-P1-C4-C1 would have location code: - + U78CA.001.1234567-P1-C4-C1-S1-S2 @@ -1742,233 +1773,233 @@ xml:lang="en">
Introduction - The set of all Vital Product Data (VPD) from the FRUs of a system - is the product topology information which uniquely defines that system’s - hardware and firmware elements. The system VPD describes a system in terms of - various FRUs, part numbers, serial numbers and other characterizing features. - With VPD, mechanisms may be provided for collecting information such as field - performance and failure data on any FRU in a system. Also, with the feedback - from the field into an installed system data base, the delivery of complete and - accurate Miscellaneous Equipment Specifications (MESs) to customers can be + The set of all Vital Product Data (VPD) from the FRUs of a system + is the product topology information which uniquely defines that system’s + hardware and firmware elements. The system VPD describes a system in terms of + various FRUs, part numbers, serial numbers and other characterizing features. + With VPD, mechanisms may be provided for collecting information such as field + performance and failure data on any FRU in a system. Also, with the feedback + from the field into an installed system data base, the delivery of complete and + accurate Miscellaneous Equipment Specifications (MESs) to customers can be assured. - R1-R1--1. - FRUs used in LoPAR platforms must - provide machine-readable VPD as defined in + FRUs used in LoPAR platforms must + provide machine-readable VPD as defined in . - + - R1-R1--2. - LoPAR platforms must support the + LoPAR platforms must support the collection of, and provide availability to, Vital Product Data. Platform Implementation Notes: - + - It is the intent of this architecture that the FRUs of a system + It is the intent of this architecture that the FRUs of a system be self describing using VPD. - There are FRU’s which have VPD which is not in the format - described herein, such as JEDEC. In the case of use of these parts, the - firmware may choose to translate the FRU VPD data into the LoPAR format when - the OF device tree is being generated. For I/O adapters which have different + There are FRU’s which have VPD which is not in the format + described herein, such as JEDEC. In the case of use of these parts, the + firmware may choose to translate the FRU VPD data into the LoPAR format when + the OF device tree is being generated. For I/O adapters which have different VPD, their device driver must perform the reading and translation. - +
VPD Data Structure Description - Architecture Note: Even though only a few - large and small resource tags have been defined (see the - ), the current definition will allow all - possible tags except for (0x00). This will allow later devices with a new, + Architecture Note: Even though only a few + large and small resource tags have been defined (see the + ), the current definition will allow all + possible tags except for (0x00). This will allow later devices with a new, previously undefined tag, to work. - R1-R1--1. - Vital Product Data when reported to the OS via - ibm,get-vpd or the OF device tree, must conform to the data - structures describe in the , section - 6.4The PCI 2.1 VPD keywords are PN, FN, - EC, MN, SN, LI, RL, RM, NA, DD, DG, LL, VI, FU, SI, and + Vital Product Data when reported to the OS via + ibm,get-vpd or the OF device tree, must conform to the data + structures describe in the , section + 6.4The PCI 2.1 VPD keywords are PN, FN, + EC, MN, SN, LI, RL, RM, NA, DD, DG, LL, VI, FU, SI, and Z0-ZZ, except as follows: - + - The VPD will consist of only the following sequence of tags: - Large Resource type identifier string tag (type 2, byte 0 = 0x82) with FRU - name, Large Resource type VPD keywords tag (type 16, byte 0 = 0x90) with FRU - VPD keywords, Small Resource type end tag (type 15) with or without checksum + The VPD will consist of only the following sequence of tags: + Large Resource type identifier string tag (type 2, byte 0 = 0x82) with FRU + name, Large Resource type VPD keywords tag (type 16, byte 0 = 0x90) with FRU + VPD keywords, Small Resource type end tag (type 15) with or without checksum covering the above. - + - Only resource tags, lengths and checksums are binary. All other + Only resource tags, lengths and checksums are binary. All other data must be in ASCII format. - + - Architecture Note: There are three keywords - (FU, SI and VI) which allow binary data. There are no other exceptions. Also, - the length code following a large resource tag is Little-Endian. That is, the - first byte is the low order byte and the second byte is the high order byte of + Architecture Note: There are three keywords + (FU, SI and VI) which allow binary data. There are no other exceptions. Also, + the length code following a large resource tag is Little-Endian. That is, the + first byte is the low order byte and the second byte is the high order byte of the length. Implementation Notes: - + - Version 2.2 of the PCI Local Bus - Specification changed the format and location of VPD information. - With that change, a device with Version 2.2 VPD will result in no VPD being - detected by the firmware. In this case the selected device driver will have to - access and reformat the VPD information so that the format of the data provided + Version 2.2 of the PCI Local Bus + Specification changed the format and location of VPD information. + With that change, a device with Version 2.2 VPD will result in no VPD being + detected by the firmware. In this case the selected device driver will have to + access and reformat the VPD information so that the format of the data provided to the OS is in the format which is required by the OS. - The definition of a small resource tag is where bit 7 is 0. Then - bit 6 through 3 are the type and bits 2 through 0 are the length. An end tag is - a type of 15. Thus a 0x78 is a small resource end tag of length 0 and 0x79 is a - small resource end tag of length 1. The valid end tags are 0x78 through + The definition of a small resource tag is where bit 7 is 0. Then + bit 6 through 3 are the type and bits 2 through 0 are the length. An end tag is + a type of 15. Thus a 0x78 is a small resource end tag of length 0 and 0x79 is a + small resource end tag of length 1. The valid end tags are 0x78 through 0x7F. - + - + - R1-R1--2. - The end tag checksum, when provided to the OS, must cover all - resources beginning with the first byte (a resource tag) up to, but not + The end tag checksum, when provided to the OS, must cover all + resources beginning with the first byte (a resource tag) up to, but not including, the Small Resource Type End tag. - + - R1-R1--3. - If the platform determines that the VPD that it has collected is - invalid, then the platform must discard any collected data and replace it + If the platform determines that the VPD that it has collected is + invalid, then the platform must discard any collected data and replace it with: - + - Large Resource type identifier string tag (type 2, byte 0 = 0x82) + Large Resource type identifier string tag (type 2, byte 0 = 0x82) with value ‘NOT_VALID_VPD’. - + - Large Resource type VPD keywords tag (type 16, byte 0 = 0x90) - containing the “YL” keyword and associated location code + Large Resource type VPD keywords tag (type 16, byte 0 = 0x90) + containing the “YL” keyword and associated location code data. - + - Small Resource Type End tag with or without a checksum covering + Small Resource Type End tag with or without a checksum covering the above. - + - + - R1-R1--4. - If the device VPD is valid, all of the + If the device VPD is valid, all of the device VPD must be transferred including the Small Resource Type End Tag. - + - R1-R1--5. - A “YL” keyword must be - added to the Large Resource type VPD keywords tag (type 16, byte 0 = 0x90) when - the VPD is reported to the OS via either the ibm,get-vpd + A “YL” keyword must be + added to the Large Resource type VPD keywords tag (type 16, byte 0 = 0x90) when + the VPD is reported to the OS via either the ibm,get-vpd RTAS call or the OF device tree. - The checksum byte after the (0x79) resource tag will cause the - binary sum of all the bytes from the first large resource tag, carries being - discarded, to result in 0x00. As noted in Requirement , the (0x79) small resource tag is not + The checksum byte after the (0x79) resource tag will cause the + binary sum of all the bytes from the first large resource tag, carries being + discarded, to result in 0x00. As noted in Requirement , the (0x79) small resource tag is not included in this sum.
Keyword Format Definition - The exact format of the VPD is vendor-specific but falls within the + The exact format of the VPD is vendor-specific but falls within the specification as defined in the following subsections.
VPD fields - The fields defined in are + The fields defined in are stored in VPD modules at the time of manufacturing. - R1-R1--1. - LoPAR platforms and FRUs must - provide VPD fields marked as required in - and for all VPD fields provided must adhere - to the definitions specified by LoPAR platforms and FRUs must + provide VPD fields marked as required in + and for all VPD fields provided must adhere + to the definitions specified by . - + - R1-R1--2. - Each system must have VPD that - contains the system’s SE keyword (see Requirements - , , - , and - ) and the system’s TM keyword (see - Requirements , - , , - and ). The description (large resource - type of 0x82) for this VPD in the “ibm,vpd” + Each system must have VPD that + contains the system’s SE keyword (see Requirements + , , + , and + ) and the system’s TM keyword (see + Requirements , + , , + and ). The description (large resource + type of 0x82) for this VPD in the “ibm,vpd” property must be “System VPD”. - + - R1-R1--3. - VPD for memory FRUs must contain + VPD for memory FRUs must contain the SZ keyword. - Platform Implementation Note: There are circumstances where vendor - preference or manufacturing processes may require that some fields be omitted - (for example; Serial Number). This should be treated as an exception and should - be accompanied by an appropriate level of risk assessment. In the case of an SN - exception, the SN should be omitted, not made blank, NULL, or a fixed + Platform Implementation Note: There are circumstances where vendor + preference or manufacturing processes may require that some fields be omitted + (for example; Serial Number). This should be treated as an exception and should + be accompanied by an appropriate level of risk assessment. In the case of an SN + exception, the SN should be omitted, not made blank, NULL, or a fixed value. @@ -2001,10 +2032,10 @@ xml:lang="en"> - Required?A lack of a hard requirement in this column does - not mean that the keyword is never required; only that it is not required all - the time. Keywords which are not marked as “Required” are + Required?A lack of a hard requirement in this column does + not mean that the keyword is never required; only that it is not required all + the time. Keywords which are not marked as “Required” are required when appropriate for the specific keyword. @@ -2031,9 +2062,9 @@ xml:lang="en"> Storage Facility Image MTMS - Logical ID - Length (MTMS-a####). Linkage between logical entities. - Examples: Used on Disk FRU resource to link disk to array site. Used on array - site resource to link array site to array. Used on array resource to link array + Length (MTMS-a####). Linkage between logical entities. + Examples: Used on Disk FRU resource to link disk to array site. Used on array + site resource to link array site to array. Used on array resource to link array to rank. Used on rank resource to link rank to segment pool. @@ -2154,15 +2185,15 @@ xml:lang="en"> -- - Contains 1 to 15 instances of the following 16 byte + Contains 1 to 15 instances of the following 16 byte definition, concatenated together. - Contains the base ethernet MAC address and an instance + Contains the base ethernet MAC address and an instance count. - The count specifies the number of valid MAC addresses - starting with the base MAC address and incrementing by one for each successive - MAC address, until the specified number of MAC addresses have been + The count specifies the number of valid MAC addresses + starting with the base MAC address and incrementing by one for each successive + MAC address, until the specified number of MAC addresses have been created. - The field contains the ASCII coded hexadecimal + The field contains the ASCII coded hexadecimal representation of the binary value, as follows: Bytes 1 - 12 Base MAC address @@ -2184,12 +2215,12 @@ xml:lang="en"> -- - Contains 1 to 7 instances of the following 32 byte + Contains 1 to 7 instances of the following 32 byte definition, concatenated together. SAS WWIDs. - The Count field is the number of available WWIDs starting + The Count field is the number of available WWIDs starting from the base and incrementing by 1 for each new WWID. - The field contains the ASCII coded hexadecimal + The field contains the ASCII coded hexadecimal representation of the binary value, as follows: Bytes 1 - 16 Base SAS WWID @@ -2246,8 +2277,8 @@ xml:lang="en"> Brand keyword value “xy” - Note: The following are the values - currently defined. To get other product specific values, go through the normal + Note: The following are the values + currently defined. To get other product specific values, go through the normal LoPAR change process. x = Type of machine @@ -2307,7 +2338,7 @@ xml:lang="en"> -- - Battery Replacement date in YYYY-MM-DD format. Used on + Battery Replacement date in YYYY-MM-DD format. Used on Primary Power Supply FRU in rack enclosure. @@ -2322,7 +2353,7 @@ xml:lang="en"> 4 - Required when a CCIN is required by code to configure or + Required when a CCIN is required by code to configure or service the component @@ -2377,22 +2408,22 @@ xml:lang="en"> -- - CEC ID - of the CEC, that is the logical controller of + CEC ID - of the CEC, that is the logical controller of an MTMS (machine-type-model-serial #), like a drawer. The 16 byte CI field definition is TTTT-MMM SSSSSSS where: - TTTT-MMM is an 8 byte field. The high order 4 bytes are - the system type, followed by a dash, followed by the 3 low order bytes which is + TTTT-MMM is an 8 byte field. The high order 4 bytes are + the system type, followed by a dash, followed by the 3 low order bytes which is the model. - blank is a 1 byte separator character, that separates + blank is a 1 byte separator character, that separates the type-model from the serial #. - SSSSSSS is the 7 byte serial number. The high order 2 - bytes are the “plant of manufacture” and the low order 5 bytes + SSSSSSS is the 7 byte serial number. The high order 2 + bytes are the “plant of manufacture” and the low order 5 bytes are the “sequence number”. @@ -2414,15 +2445,15 @@ xml:lang="en"> Code Level, LID keyword Format: - fix pack MIF name, “space”, Load ID (8 + fix pack MIF name, “space”, Load ID (8 characters), time stamp (12 characters) - The fix pack name must be the same as the name used in + The fix pack name must be the same as the name used in the MI keyword and is delimited by a space. - The time stamp is, hours (2 characters) + Minutes (2 - characters) + Year (4 characters) + Month (2 characters) + Day (2 characters). + The time stamp is, hours (2 characters) + Minutes (2 + characters) + Year (4 characters) + Month (2 characters) + Day (2 characters). The LID level reported is the current active level. - Note: There is no correlation - between the CL keyword value and which of the 3 candidate fixpack levels are + Note: There is no correlation + between the CL keyword value and which of the 3 candidate fixpack levels are reported in the MI keyword. @@ -2601,13 +2632,13 @@ xml:lang="en"> Disk Space Characteristics Used on Disk resource. Comma separated string. - Example (in the following, the “<“, - “>”, and text in between these would be replaced by a value - representing the quantity specified by the words between “<” + Example (in the following, the “<“, + “>”, and text in between these would be replaced by a value + representing the quantity specified by the words between “<” and “>”): - “VN=<Volume Serial Number>, - VD=<Vendor>, DT=<Disk Type>, DC=<Disk-Capacity>, - DR=<Disk-RPM>, DS=<Disk-Interface-Speed>, + “VN=<Volume Serial Number>, + VD=<Vendor>, DT=<Disk Type>, DC=<Disk-Capacity>, + DR=<Disk-RPM>, DS=<Disk-Interface-Speed>, AP=<Array-Site-Position>, ST=<Status>” @@ -2625,7 +2656,7 @@ xml:lang="en"> -- - Displayable Message (if not defined, created by the + Displayable Message (if not defined, created by the contents of the ID large resource (82)) @@ -2678,15 +2709,15 @@ xml:lang="en"> Enclosure Type. - This value is defined in the - . The ASCII value specified below is the - ASCII representation of the hexadecimal representation of the byte value - defined in the SMBIOS specification (for example, 0x0B becomes - “0B”). Bit 7 of the byte number is the chassis lock bit (if - present value is a 1, otherwise if either a lock is not present or it is - unknown if the enclosure has a lock, the value is a 0). If the chassis lock bit - is set, the following get changed to the corresponding ASCII representation - (for example, “01” becomes “81”, “10” + This value is defined in the + . The ASCII value specified below is the + ASCII representation of the hexadecimal representation of the byte value + defined in the SMBIOS specification (for example, 0x0B becomes + “0B”). Bit 7 of the byte number is the chassis lock bit (if + present value is a 1, otherwise if either a lock is not present or it is + unknown if the enclosure has a lock, the value is a 0). If the chassis lock bit + is set, the following get changed to the corresponding ASCII representation + (for example, “01” becomes “81”, “10” becomes “90”) “01” Other “02” Unknown @@ -2728,7 +2759,7 @@ xml:lang="en"> -- - The Feature Code is 8 bytes formatted as 4 characters, a + The Feature Code is 8 bytes formatted as 4 characters, a dash, and three characters. @@ -2763,11 +2794,11 @@ xml:lang="en"> -- - FlaG Field: The first two bytes contain a VPD flag in - the form of VS. V=V indicates that there is VPD. V=N indicates there is no VPD. - S=S indicates that the VPD contains a slot map. S=P indicates there is a port - map. S=N indicates no slot map or port map. S=B indicates both a slot map and a - port map. The right two characters contain the FRU identification + FlaG Field: The first two bytes contain a VPD flag in + the form of VS. V=V indicates that there is VPD. V=N indicates there is no VPD. + S=S indicates that the VPD contains a slot map. S=P indicates there is a port + map. S=N indicates no slot map or port map. S=B indicates both a slot map and a + port map. The right two characters contain the FRU identification keyword. @@ -2785,7 +2816,7 @@ xml:lang="en"> -- - Frame ID: 2 hex byte value for SPCN or 8 character + Frame ID: 2 hex byte value for SPCN or 8 character logical frame number for DASD backplane. @@ -2803,7 +2834,7 @@ xml:lang="en"> -- - FRU Label: This is a variable length ASCII character + FRU Label: This is a variable length ASCII character data area for the FRU Label. @@ -2821,7 +2852,7 @@ xml:lang="en"> Required - FRU Number (Board, card, or assembly Field Replacement + FRU Number (Board, card, or assembly Field Replacement Unit number). @@ -2839,8 +2870,8 @@ xml:lang="en"> -- - Function Unit - This function identifies which function - in a multi-function IOA this VPD data applies to. Only one FU field can appear + Function Unit - This function identifies which function + in a multi-function IOA this VPD data applies to. Only one FU field can appear per VPD tag. Data is binary encoded. @@ -2876,7 +2907,7 @@ xml:lang="en"> -- - Two ASCII characters are used to identify each system in + Two ASCII characters are used to identify each system in a Storage Facility. Valid values are 00 and 01. @@ -2895,11 +2926,11 @@ xml:lang="en"> Storage Facility MTMS - InterfaceID - Length (MTMS-####). Identifies one or more adapter I/O - interfaces in the storage facility that interconnect device adapters and - storage enclosures. Used on Device Adapter FRUs in I/O enclosure and on Storage - Enclosures. Device Adapters have two Interfaces Ids (comma separated string), - and storage enclosures have one. The number could change for future + Length (MTMS-####). Identifies one or more adapter I/O + interfaces in the storage facility that interconnect device adapters and + storage enclosures. Used on Device Adapter FRUs in I/O enclosure and on Storage + Enclosures. Device Adapters have two Interfaces Ids (comma separated string), + and storage enclosures have one. The number could change for future products. @@ -2952,7 +2983,7 @@ xml:lang="en"> -- - LIC Node Alternate Bus VPD: This fixed format data field + LIC Node Alternate Bus VPD: This fixed format data field contains 32 bytes of LIC I/O node alternate bus VPD data. @@ -2971,8 +3002,8 @@ xml:lang="en"> LIC VMRF - Example: SEA 5.1.0.0345. Used on a partition resource - that is part of a storage facility image or on an enclosure or enclosure + Example: SEA 5.1.0.0345. Used on a partition resource + that is part of a storage facility image or on an enclosure or enclosure resource that has a firmware level. @@ -3078,15 +3109,15 @@ xml:lang="en"> Logical Space Characteristics Used on Storage Logical resources. Examples: - Used on Array resource. Comma separated string. - Including: “AN=Array Serial Number, AT=Array-Type, AC=Array + Used on Array resource. Comma separated string. + Including: “AN=Array Serial Number, AT=Array-Type, AC=Array Configuration, Rank Position”. - Used on Rank resource. Comma separated string. Including: - “RN=Rank Serial Number, ST=Segment-Type(FB-1G, CKD-Mod1), + Used on Rank resource. Comma separated string. Including: + “RN=Rank Serial Number, ST=Segment-Type(FB-1G, CKD-Mod1), SS=Segments(####), SU=Segments-Used, RG=Rank Group(#)”. - Used on Segment Pool resource. Comma separated string. - Including: “ST=Segment-Type(FB-1G, CKD-Mod1), SS=Segments(####), - SU=Segments-Used, VS=Virtual-Segments(####), + Used on Segment Pool resource. Comma separated string. + Including: “ST=Segment-Type(FB-1G, CKD-Mod1), SS=Segments(####), + SU=Segments-Used, VS=Virtual-Segments(####), VU=Virtual-Segments-Used(####)”, RG=Rank-Group(#). @@ -3122,8 +3153,8 @@ xml:lang="en"> Microcode Service Entitlement Expiration Date - This is the date a customer's system firmware service warranty period - expires. System firmware images with MG dates that are later than a system's + This is the date a customer's system firmware service warranty period + expires. System firmware images with MG dates that are later than a system's ME date are not entitled to be flashed on that system. Format:yyyymmdd @@ -3142,8 +3173,8 @@ xml:lang="en"> -- - Map Format: Two hex characters identify the slot or port - map format that follows. This keyword must immediately precede the SM or PM + Map Format: Two hex characters identify the slot or port + map format that follows. This keyword must immediately precede the SM or PM keyword. @@ -3181,35 +3212,35 @@ xml:lang="en"> Microcode Image - This keyword is only used to describe dual sided - alterable system firmware Image which can be altered by the OS via the - ibm,update-flash-64-and-reboot RTAS call. Both the - ibm,validate-flash-image and the - ibm,manage-flash-image RTAS calls are supported. May or may not be + This keyword is only used to describe dual sided + alterable system firmware Image which can be altered by the OS via the + ibm,update-flash-64-and-reboot RTAS call. Both the + ibm,validate-flash-image and the + ibm,manage-flash-image RTAS calls are supported. May or may not be able to be updated via non-OS visible means. Format: - t side Microcode Image name, “space”, p - side Microcode Image name, “space”, booted Microcode Image + t side Microcode Image name, “space”, p + side Microcode Image name, “space”, booted Microcode Image name - The Microcode Image name must be a 9 character name of + The Microcode Image name must be a 9 character name of the form: “NNSSS_FFF” where - “NN” is a two character name (assigned by - the GFW Firmware Distribution Coordinator) used to identify a set of + “NN” is a two character name (assigned by + the GFW Firmware Distribution Coordinator) used to identify a set of platforms; - “SSS” is a 3 character code stream + “SSS” is a 3 character code stream indicator; - “_” is a separation character for + “_” is a separation character for readability; and, - “FFF” is a 3 character identifier of the + “FFF” is a 3 character identifier of the current microcode level. - Note: The booted fix pack level - reported may not match the current p-side or t-side level as a result of - concurrent update. The important information is what is in flash, and that is - what is being reported. The hypervisor will have to cache the value for the - booted level, and should go to FSP to check what's current on flash for the + Note: The booted fix pack level + reported may not match the current p-side or t-side level as a result of + concurrent update. The important information is what is in flash, and that is + what is being reported. The hypervisor will have to cache the value for the + booted level, and should go to FSP to check what's current on flash for the p-side and t-side levels. @@ -3228,14 +3259,14 @@ xml:lang="en"> Microcode Level - This keyword is only used to describe dual sided - alterable system firmware images which can be altered by the OS via the - ibm,update-flash-64-and-reboot RTAS call. Both the ibm,validate-flash-image and - the ibm,manage-flash-image RTAS calls are supported. May or may not be able to + This keyword is only used to describe dual sided + alterable system firmware images which can be altered by the OS via the + ibm,update-flash-64-and-reboot RTAS call. Both the ibm,validate-flash-image and + the ibm,manage-flash-image RTAS calls are supported. May or may not be able to be updated via non-OS visible means. Format: - t side Microcode Level name, “space”, p - side Microcode Level name, “space”, booted Microcode Level + t side Microcode Level name, “space”, p + side Microcode Level name, “space”, booted Microcode Level name The Microcode Image name must be a 8 character name of the form: “FWVRE.MF” @@ -3244,16 +3275,16 @@ xml:lang="en"> "FW" is a static prefix representing 'firmware' “V” is Version - Power Processor Level "R" is Revision - Typically GA number from the processor level - "E" is Extension - Typically zero. If non-zero, + "E" is Extension - Typically zero. If non-zero, designates off cycle single system release "M" is Modification - associated Service Pack Level (0-Z) - "F" is Fix Level - Typically zero. If non-zero, designate + "F" is Fix Level - Typically zero. If non-zero, designate off cycle, targeted fixes - Note: The booted fix pack level - reported may not match the current p-side or t-side level as a result of - concurrent update. The important information is what is in flash, and that is - what is being reported. The hypervisor will have to cache the value for the - booted level, and should go to FSP to check what's current on flash for the + Note: The booted fix pack level + reported may not match the current p-side or t-side level as a result of + concurrent update. The important information is what is in flash, and that is + what is being reported. The hypervisor will have to cache the value for the + booted level, and should go to FSP to check what's current on flash for the p-side and t-side levels. @@ -3288,8 +3319,8 @@ xml:lang="en"> -- - Module Plug count. This counter keeps track of the - numbers of times a module has been plugged, so that reliability statistics can + Module Plug count. This counter keeps track of the + numbers of times a module has been plugged, so that reliability statistics can be kept. @@ -3324,7 +3355,7 @@ xml:lang="en"> -- - Machine Universal Unit ID (UUID). The value is the ASCII + Machine Universal Unit ID (UUID). The value is the ASCII coded hexadecimal representation of the 16 byte binary value. @@ -3410,7 +3441,7 @@ xml:lang="en"> -- - Network Address (ASCII coded hexadecimal representation + Network Address (ASCII coded hexadecimal representation of the binary value.) @@ -3428,10 +3459,10 @@ xml:lang="en"> -- - This keyword is used to describe the prefix name of the - file used to install a single sided alterable system firmware or adapter/device - microcode image. When this keyword is present, the complete file name will be - described by the content of the NC keyword, concatenated with + This keyword is used to describe the prefix name of the + file used to install a single sided alterable system firmware or adapter/device + microcode image. When this keyword is present, the complete file name will be + described by the content of the NC keyword, concatenated with “.”, concatenated with the content of the RM keyword. @@ -3449,7 +3480,7 @@ xml:lang="en"> -- - World Wide Node Name - IEEE assigned 64 bit identifier + World Wide Node Name - IEEE assigned 64 bit identifier (16 hexadecimal digits) for Storage Facility. Valid values are 0-9, A-F. @@ -3519,7 +3550,7 @@ xml:lang="en"> OS name and level. - The OS level is shown in the form of: V.R.M.F where V is + The OS level is shown in the form of: V.R.M.F where V is the version, R is the release, M is the modification, and F is the fix. @@ -3537,8 +3568,8 @@ xml:lang="en"> -- - Op Panel installed flag. “Y” = yes a panel - is installed, “N” = no a panel is not installed. The absence of + Op Panel installed flag. “Y” = yes a panel + is installed, “N” = no a panel is not installed. The absence of this keyword means, that an Op Panel is installed. @@ -3624,7 +3655,7 @@ xml:lang="en"> -- - Port Map: Contains the RIO Port Map label information. + Port Map: Contains the RIO Port Map label information. Must be preceded by the MF keyword. @@ -3639,7 +3670,7 @@ xml:lang="en"> 12 - Required if it is different from the FRU number + Required if it is different from the FRU number (FN) @@ -3660,7 +3691,7 @@ xml:lang="en"> -- - SPCN VPD: Identification of the SPCN VPD area on the I/O + SPCN VPD: Identification of the SPCN VPD area on the I/O backplane. @@ -3678,7 +3709,7 @@ xml:lang="en"> -- - Power Parameters: SPCN field identifying Power node + Power Parameters: SPCN field identifying Power node parameters. @@ -3696,7 +3727,7 @@ xml:lang="en"> -- - Power: 16 ASCII hexadecimal characters that represent + Power: 16 ASCII hexadecimal characters that represent the 8 bytes of binary information for Power Control. @@ -3715,7 +3746,7 @@ xml:lang="en"> Rack MTMS - Rack Location - Length (MTMS-Exx). - used on storage enclosure + Length (MTMS-Exx). - used on storage enclosure resources. @@ -3734,7 +3765,7 @@ xml:lang="en"> Rack Number - Used on Rack enclosure resources. Provides an ordered + Used on Rack enclosure resources. Provides an ordered number of racks in the storage facility. @@ -3769,22 +3800,22 @@ xml:lang="en"> -- - Power Domain ID - is the MTMS of the BPA, that powers an + Power Domain ID - is the MTMS of the BPA, that powers an MTMS (Machine-Type-Model-Serial #), like a CEC or drawer. The 16 byte RD field definition is: TTTT-MMM SSSSSSS where: - TTTT-MMM is an 8 byte field. The high order 4 bytes are - the system type, followed by a dash, followed by the 3 low order bytes which is + TTTT-MMM is an 8 byte field. The high order 4 bytes are + the system type, followed by a dash, followed by the 3 low order bytes which is the model. - blank is a 1 byte separator character, that separates + blank is a 1 byte separator character, that separates the type-model from the serial #. - SSSSSSS is the 7 byte serial number. The high order 2 - bytes are the “plant of manufacture” and the low order 5 bytes + SSSSSSS is the 7 byte serial number. The high order 2 + bytes are the “plant of manufacture” and the low order 5 bytes are the “sequence number”. @@ -3804,7 +3835,7 @@ xml:lang="en"> -- - Power Resource ID: A 4 byte hex field providing a unique + Power Resource ID: A 4 byte hex field providing a unique logical ID for the power resource. @@ -3823,7 +3854,7 @@ xml:lang="en"> RIO-G Loop - Used on I/O enclosure resource. Identifies RIO-G loop on + Used on I/O enclosure resource. Identifies RIO-G loop on the reporting system. @@ -3841,11 +3872,11 @@ xml:lang="en"> -- - Rack Unique ID - is the 64 bit Dallas - “1-wire” unique ROM code. The first 8 bits are a 1-Wire family - code. The next 48 bits are a unique serial number. The last 8 bits are a CRC of + Rack Unique ID - is the 64 bit Dallas + “1-wire” unique ROM code. The first 8 bits are a 1-Wire family + code. The next 48 bits are a unique serial number. The last 8 bits are a CRC of the first 56 bits. - Each of the 16 4-bit nibbles are converted to 16 ASCII + Each of the 16 4-bit nibbles are converted to 16 ASCII characters, in the range 0-9 or A-F. @@ -3863,11 +3894,11 @@ xml:lang="en"> -- - This keyword is only used to describe single sided - non-alterable system firmware or adapter/device microcode image which can not - be altered by any means; OS visible or non-OS visible. A single alphanumeric + This keyword is only used to describe single sided + non-alterable system firmware or adapter/device microcode image which can not + be altered by any means; OS visible or non-OS visible. A single alphanumeric character string that defines the level of the image. - ROM id, Location ID, ROM part number, FW part number, FW + ROM id, Location ID, ROM part number, FW part number, FW level, FW code, release date, FW size. @@ -3885,15 +3916,15 @@ xml:lang="en"> -- - This keyword is only used to describe single sided - alterable system firmware or adapter/device microcode image which can be - altered by the OS. The OS alters the system firmware image via the - ibm,update-flash-64-and-reboot RTAS call. Neither the - ibm,validate-flash-image nor the - ibm,manage-flash-image RTAS calls are supported. May or may not be - able to be updated via non-OS visible means. A single alphanumeric character + This keyword is only used to describe single sided + alterable system firmware or adapter/device microcode image which can be + altered by the OS. The OS alters the system firmware image via the + ibm,update-flash-64-and-reboot RTAS call. Neither the + ibm,validate-flash-image nor the + ibm,manage-flash-image RTAS calls are supported. May or may not be + able to be updated via non-OS visible means. A single alphanumeric character string that defines the level of the image. - ROM id, Location ID, ROM part number, FW part number, FW + ROM id, Location ID, ROM part number, FW part number, FW level, FW code, release date, FW size @@ -3929,7 +3960,7 @@ xml:lang="en"> RIO-G Position Offset - Used on I/O enclosure resource. Identifies the distance + Used on I/O enclosure resource. Identifies the distance in enclosures from the reporting system - first enclosure is offset 1. @@ -3964,8 +3995,8 @@ xml:lang="en"> -- - Record Type. Contains a four character Record Name that - represents a VPD Definition. The following list associates Record Names with + Record Type. Contains a four character Record Name that + represents a VPD Definition. The following list associates Record Names with their VPD Definitions. @@ -4011,9 +4042,9 @@ xml:lang="en"> -- - This keyword is only used to describe single sided - microcode image which can not be altered by the OS, but may be updated via - non-OS visible means. A single alphanumeric character string that defines the + This keyword is only used to describe single sided + microcode image which can not be altered by the OS, but may be updated via + non-OS visible means. A single alphanumeric character string that defines the level of the image. @@ -4049,9 +4080,9 @@ xml:lang="en"> Storage Facility MTMS - Length (MTMS). Used on system resource, partition - resources, array-site, resources, array resources, rank resources, storage pool - resources, and enclosure resources in a storage facility to identify the + Length (MTMS). Used on system resource, partition + resources, array-site, resources, array resources, rank resources, storage pool + resources, and enclosure resources in a storage facility to identify the storage facility. @@ -4070,8 +4101,8 @@ xml:lang="en"> Storage Facility Image MTMS - Length (MTMS). Used on partition, array-site, array, - rank, and storage pool, and enclosure-FRU resources, associated with a storage + Length (MTMS). Used on partition, array-site, array, + rank, and storage pool, and enclosure-FRU resources, associated with a storage facility image. @@ -4103,11 +4134,11 @@ xml:lang="en"> Up to 7 - See Requirements - , + See Requirements + , , - , - , and + , + , and @@ -4145,11 +4176,11 @@ xml:lang="en"> -- - 2 high order bytes are the “plant of manufacture - code”, followed by the low order 5 bytes, which are the “unit - sequence number”. This unit sequence number must be DDDD0, ADDD0, AADD0, - AAAD0, or AAAA0 where D is a digit 0-9 and A is an alphabetic character A-Z - excluding E, I, J, O, Q, S, U. The right most character of the unit sequence + 2 high order bytes are the “plant of manufacture + code”, followed by the low order 5 bytes, which are the “unit + sequence number”. This unit sequence number must be DDDD0, ADDD0, AADD0, + AAAD0, or AAAA0 where D is a digit 0-9 and A is an alphabetic character A-Z + excluding E, I, J, O, Q, S, U. The right most character of the unit sequence number must be set to 0. @@ -4201,7 +4232,7 @@ xml:lang="en"> -- - Slot Map: Contains Slot Map information. Must be + Slot Map: Contains Slot Map information. Must be preceded by the MF keyword. @@ -4236,10 +4267,10 @@ xml:lang="en"> See notes - The System Unique Identifier (SUID) is a twelve - hexadecimal character value that is unique to a given system anywhere in the - world. The number range is obtained from the Institute of Electrical and - Electronic Engineers. There are no IBM asset protection considerations + The System Unique Identifier (SUID) is a twelve + hexadecimal character value that is unique to a given system anywhere in the + world. The number range is obtained from the Institute of Electrical and + Electronic Engineers. There are no IBM asset protection considerations involved. @@ -4277,8 +4308,8 @@ xml:lang="en"> - Size in decimal, with no leading zeroes. For memory (for - example, cards and DIMMs), it provides the memory size in MB’s. As an + Size in decimal, with no leading zeroes. For memory (for + example, cards and DIMMs), it provides the memory size in MB’s. As an example, a 32 GB memory card would be coded as 32768. @@ -4310,16 +4341,16 @@ xml:lang="en"> 8 - See Requirements + See Requirements , , , - , and + , and - The high order 4 bytes are the “Machine - Type”, the next byte is a dash, followed by the 3 byte + The high order 4 bytes are the “Machine + Type”, the next byte is a dash, followed by the 3 byte “Model”. @@ -4337,8 +4368,8 @@ xml:lang="en"> -- - The high order 4 bytes are the “Machine - Type”, the next byte is a dash, followed by the 3 byte + The high order 4 bytes are the “Machine + Type”, the next byte is a dash, followed by the 3 byte “Model”. @@ -4357,12 +4388,12 @@ xml:lang="en"> Logical Configuration String - Used on a partition resource that is: CKD3380=####, - CKD3390=####, SCSI512=####, SCSI520=####, SCSI Host Ports=####, SCSI LUN + Used on a partition resource that is: CKD3380=####, + CKD3390=####, SCSI512=####, SCSI520=####, SCSI Host Ports=####, SCSI LUN Groups=####. - Used on device adapter or host adapter FRU for logical + Used on device adapter or host adapter FRU for logical configuration information, if any. - Used on Storage Enclosure. Comma separated string + Used on Storage Enclosure. Comma separated string including “BA=Base Address(xx)”. @@ -4381,9 +4412,9 @@ xml:lang="en"> Host Inventory - Used on a partition resource that is part of a storage - facility image for storage facility image logical configuration. Comma - separated string. Including: “Host OS Type1=####, Host OS Type 2=####, . + Used on a partition resource that is part of a storage + facility image for storage facility image logical configuration. Comma + separated string. Including: “Host OS Type1=####, Host OS Type 2=####, . . .”. @@ -4401,7 +4432,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4419,7 +4450,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4437,7 +4468,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4455,7 +4486,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4473,7 +4504,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4491,7 +4522,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4509,7 +4540,7 @@ xml:lang="en"> -- - Reserved for future use. Used on partition resource or + Reserved for future use. Used on partition resource or Storage Configuration resources. @@ -4562,7 +4593,7 @@ xml:lang="en"> -- - Contains the ASCII coded hexadecimal World Wide Port + Contains the ASCII coded hexadecimal World Wide Port Name (WWPN). @@ -4580,7 +4611,7 @@ xml:lang="en"> See Requirement - Ties together multiple enclosures that share the same + Ties together multiple enclosures that share the same combined SE and TM. @@ -4589,26 +4620,26 @@ xml:lang="en"> Notes referenced in : - + - When the - BR keyword indicates “S” or “T” for the type of + When the + BR keyword indicates “S” or “T” for the type of machine, this field must be present and must be non-blank. - - Implementation Note: The following keywords - are defined in this architecture with the same or similar usage: AD, CD, DC, + + Implementation Note: The following keywords + are defined in this architecture with the same or similar usage: AD, CD, DC, DL, DS, DU, EC, FC, FN, LO, NA, P C, PI, PN, RL, RN, SN, SZ, TM, and US.
Additional Fields for Product Specific use - Three fields are available for user, system or product specific - data for which no unique keyword has been defined. The first and second ranges - of fields in the list are not addressed in the PCI Specifications and are + Three fields are available for user, system or product specific + data for which no unique keyword has been defined. The first and second ranges + of fields in the list are not addressed in the PCI Specifications and are unique to LoPAR platforms. - + U0 - UZ User specific @@ -4624,13 +4655,13 @@ xml:lang="en"> Z0 - ZZ Product specific - - Note: If firmware/software has a specific - need for a keyword, then it must be provided by the appropriate component + + Note: If firmware/software has a specific + need for a keyword, then it must be provided by the appropriate component VPD. - The Y? and Z? fields defined in - are specific to LoPAR platforms. As a need - for these fields is determined, they will be defined in this document. The + The Y? and Z? fields defined in + are specific to LoPAR platforms. As a need + for these fields is determined, they will be defined in this document. The table contains several keywords which have been defined as place holders. @@ -4788,8 +4819,8 @@ xml:lang="en"> Up to 4 - Ties together multiple enclosures that share the same - combined SE and TM. See Requirement + Ties together multiple enclosures that share the same + combined SE and TM. See Requirement . @@ -4818,7 +4849,7 @@ xml:lang="en"> Up to 255 - Product Specific Information: may be keyword oriented + Product Specific Information: may be keyword oriented and ‘,’ delimited. diff --git a/Platform/ch_system_reqs.xml b/Platform/ch_system_reqs.xml index 6bbda20..8e6eb3d 100644 --- a/Platform/ch_system_reqs.xml +++ b/Platform/ch_system_reqs.xml @@ -2566,6 +2566,21 @@ ELSE . + + + Coherent Platform Facility + + + O + + + O + + + Allows partitions to resize their HPT. See + . + +
diff --git a/RTAS/sec_rtas_get_indices.xml b/RTAS/sec_rtas_get_indices.xml index 56b5b34..1a52c84 100644 --- a/RTAS/sec_rtas_get_indices.xml +++ b/RTAS/sec_rtas_get_indices.xml @@ -91,7 +91,7 @@ - + In @@ -177,7 +177,7 @@ - + Out @@ -512,7 +512,7 @@ - + In @@ -1038,7 +1038,7 @@ - + In @@ -1120,7 +1120,7 @@ - + Out @@ -1411,7 +1411,7 @@ - + In @@ -1485,7 +1485,7 @@ - + Out @@ -1662,7 +1662,7 @@ - + In @@ -1752,7 +1752,7 @@ - + Out @@ -1937,7 +1937,7 @@ - + In @@ -2269,7 +2269,7 @@ - +   @@ -2620,7 +2620,7 @@ - + In @@ -2721,7 +2721,7 @@ Initial Format of Work Area for <emphasis>ibm,update-nodes</emphasis> - + @@ -2763,7 +2763,7 @@ Format of Work Area for <emphasis>ibm,update-nodes</emphasis> - + @@ -2935,7 +2935,7 @@ Format of Work Area for Subsequent Calls to <emphasis>ibm,update-nodes</emphasis> - + @@ -2980,259 +2980,43 @@ for the value of the specified “Scope” argument. - - Nodes That May be Reported by - <emphasis>ibm,update-nodes</emphasis> for a Given Value of the “ - <emphasis>Scope</emphasis>” Argument - - - - - - - - Scope Value - - - Reportable node types (value of - “name” or - “device_type” property) - - - Supported Opcodes - - - + + + + + R1--20. + + The work area on the first call to + ibm,update-nodes RTAS for a given value of + "Scope" must be formatted as specified in + + else RTAS may return -3 "Parameter Error". + +
+ Initial Format of Work Area for + <emphasis>ibm,update-nodes</emphasis> with Device Reconfiguration Scope + + - - - Negative values: Platform Resource Reassignment events as - from - event-scan RTAS - - - cpu - - - 0x02 - - - - - memory - - - 0x02 - - - - - ibm,dynamic-reconfiguration-memory - - - 0x02 - - - - - - ibm,plaform-facilities - - - - 0x01-0x03 - - - - ibm,random-v# - - - - 0x01-0x03 + 0x00000000 (State Variable indicates Initial call for specified Scope) - - ibm,compression-v# - - - - 0x01-0x03 + Unit Address of target device for reconfiguration - - ibm,encryption-v# - - - - 0x01-0x03 + 4 bytes of 0x00 (reserved) - - ibm,memory-utilization_instrumentation-v# - - - - 0x01-0x03 - - - - - 1 Partition Migration / Hibernation - - - - root - - - - 0x02 - - - - - - openprom - - - - 0x02 - - - - - - rtas - - - - 0x02 - - - - - - vdevice - - - - 0x02 - - - - - - cpu - - - - 0x02 - - - - - - cache - - - - 0x01-0x03 - - - - - - options - - - - 0x02 - - - - - - memory - - - - 0x02 - - - - - ibm,dynamic-reconfiguration-memory - - - <all> - - - - - ibm,platform-facilities - - - 0x01-0x03 - - - - - - ibm,random-v# - - - - 0x01-0x03 - - - - - - ibm,compression-v# - - - - 0x01-0x03 - - - - - - ibm,encryption-v# - - - - 0x01-0x03 - - - - - - ibm,memory-utilization_instrumentation-v# - - - - 0x01-0x03 - - - - - 2 Activate Firmware - - - - rtas - - - - 0x02 + Don't Care. . . @@ -3240,8 +3024,291 @@
+ + + Nodes That May be Reported by + <emphasis>ibm,update-nodes</emphasis> for a Given Value of the + “<emphasis>Scope</emphasis>” Argument + + + + + + + + Scope Value + + + Reportable node types (value of + “name” or + “device_type” property) + + + Supported Opcodes + + + + + + + Negative values: Platform Resource Reassignment events as + from + event-scan RTAS + + + cpu + + + 0x02 + + + + + memory + + + 0x02 + + + + + ibm,dynamic-reconfiguration-memory + + + 0x02 + + + + + + ibm,plaform-facilities + + + + 0x01-0x03 + + + + + + ibm,random-v# + + + + 0x01-0x03 + + + + + + ibm,compression-v# + + + + 0x01-0x03 + + + + + + ibm,encryption-v# + + + + 0x01-0x03 + + + + + + ibm,memory-utilization_instrumentation-v# + + + + 0x01-0x03 + + + + + 1 Partition Migration / Hibernation + + + + root + + + + 0x02 + + + + + + openprom + + + + 0x02 + + + + + + rtas + + + + 0x02 + + + + + + vdevice + + + + 0x02 + + + + + + cpu + + + + 0x02 + + + + + + cache + + + + 0x01-0x03 + + + + + + options + + + + 0x02 + + + + + + memory + + + + 0x02 + + + + + ibm,dynamic-reconfiguration-memory + + + <all> + + + + + ibm,platform-facilities + + + 0x01-0x03 + + + + + + ibm,random-v# + + + + 0x01-0x03 + + + + + + ibm,compression-v# + + + + 0x01-0x03 + + + + + + ibm,encryption-v# + + + + 0x01-0x03 + + + + + + ibm,memory-utilization_instrumentation-v# + + + + 0x01-0x03 + + + + + 2 Activate Firmware + + + + rtas + + + + 0x02 + + + + + 3 Device Reconfiguration + + + + ibm,coherent-platform-facility + + + + 0x02 + + + + + + ibm,coherent-platform-function + + + + 0x02 + + + + +
+
@@ -3326,7 +3393,7 @@ - + In @@ -3381,7 +3448,7 @@ - + Out @@ -3689,7 +3756,7 @@ - + All negative values: Resource Reassignment events as from event-scan RTAS @@ -3758,10 +3825,10 @@ - + 1 Partition Migration / Hibernation - + root @@ -3914,7 +3981,7 @@ - + rtas @@ -3994,7 +4061,7 @@ - + vdevice @@ -4024,11 +4091,11 @@ - + 1 Partition Migration / Hibernation   - + cpu @@ -4180,7 +4247,7 @@ - + cache @@ -4244,7 +4311,7 @@ - + ibm,dynamic-reconfiguration-memory @@ -4279,7 +4346,7 @@ - + 1 Partition Migration / Hibernation   @@ -4357,6 +4424,264 @@ of that RTAS function call does not change. + + + 3 Device Reconfiguration + + + + ibm,coherent-platform-facility + + + + + “compatible” + + + + + + + “status” + + + + + + + “ibm,caia-version” + + + + + + + “ibm,psl-revision” + + + + + + + “ibm,vpd-size” + + + + + + + “vendor-id” + + + + + + + “device-id” + + + + + + + “subsystem-id” + + + + + + + “subsystem-vendor-id” + + + + + + + “revision-id” + + + + + + + “class-code” + + + + + + + ibm,coherent-platform-function + + + + + “compatible” + + + + + + + “reg” + + + + + + + “ibm,max-ints-per-process” + + + + + + + “ibm,min-ints-per-process” + + + + + + + “ibm,#processes” + + + + + + + “ibm,config-record-type” + + + + + + + “ibm,config-record-size” + + + + + + + “ibm,#config-records” + + + + + + + “ibm,error-buffer-size” + + + + + + + “ibm,vpd-size” + + + + + + + “ibm,scratchpad-size” + + + + + + + “vendor-id” + + + + + + + “device-id” + + + + + + + “subsystem-id” + + + + + + + “subsystem-vendor-id” + + + + + + + “revision-id” + + + + + + + “class-code” + + + + + + + “ibm,process-mmio” + + + + + + + “ibm,supports-aur” + + + + + + + “ibm,supports-csrp” + + + + + + + “ibm,supports-prr” + + + + + + + “ibm,process-mmio-size” + + + + + + + “ibm,programming-model” + + + + + + + “ibm,programming-models” + + + @@ -4406,7 +4731,7 @@ - + In @@ -5193,7 +5518,7 @@ - + In @@ -5264,7 +5589,7 @@ - + Out @@ -5423,7 +5748,7 @@ - + In @@ -5513,7 +5838,7 @@ - + Out @@ -5650,7 +5975,7 @@ - + In @@ -5920,7 +6245,7 @@ - + In diff --git a/Virtualization/ch_dynamic_reconfig.xml b/Virtualization/ch_dynamic_reconfig.xml index 1361f22..7aaa82d 100644 --- a/Virtualization/ch_dynamic_reconfig.xml +++ b/Virtualization/ch_dynamic_reconfig.xml @@ -7,7 +7,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> able to use the new configuration, all without having to turn the platform power off or restart the OS. This section will define the requirements for systems that support DR operations. - +
DR Architecture Structure @@ -34,13 +34,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> other DR entities is to do the physical hot plug (power up/down, control of service indicators, etc.) via the HMC and to bring the entity into usage by an OS via logical DR operations (Logical Resource DR -- LRDR). The PCI Hot - Plug DR option can be found in + Plug DR option can be found in . The Logical Resource Dynamic - Reconfiguration option can be found in + Reconfiguration option can be found in . It is expected that as time goes on, the base DR option may be expanded upon by addition of other DR options. - +
DR Architecture Structure @@ -55,7 +55,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- +
Definitions Used in DR @@ -88,7 +88,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Specific DR options include, for example, the PCI Hot Plug DR option, processor card DR option, etc. These specific DR options each include the requirement that all the base DR option - requirements be met. See + requirements be met. See for more information about the structure of the DR architecture pieces. @@ -188,7 +188,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> an IOA. The term “IOA” without the usage of the qualifier “physical” or “virtual” will be used to designate a physical IOA. Virtual IOAs are defined - further in + further in . Resources which must have the capability of being separate (from other devices) include: MMIO Load/Store address spaces, configuration address @@ -282,7 +282,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> A DR entity which does not have to be physically plugged or - unplugged during a DR operation on that entity. See + unplugged during a DR operation on that entity. See for a list of the supported Logical DR types. @@ -293,7 +293,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The name of the option for support of DR of logical - entities. See + entities. See . @@ -316,7 +316,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> A DR entity which may need to be physically plugged or - unplugged during a DR operation on that entity. See + unplugged during a DR operation on that entity. See for a list of the supported physical DR types. @@ -350,7 +350,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The DR architecture places a few limitations on the implementations. Current architectural limitations include: - + DR operations will be user initiated at the software level before any physical plugging or unplugging of hardware is performed. This @@ -362,7 +362,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> plugging/unplugging without the user first informing the software (for example, P1394 and USB). - + Critical system resources cannot be removed via a DR operation. Which system resources are critical will not be defined by this @@ -370,27 +370,27 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> implementation and/or architecture. Loss of a critical resource would stop the system from operating. - + Many of the RTAS calls will need to work properly, independent of what is powered-off (for example, NVRAM access must work during DR operations). This is partially encompassed by the last bullet. For more - information, see + information, see . - + Any special requirements relative to redundant power supplies or cooling are not addressed here. - + Moving of a DR entity from one location to another in a platform is supported through a “remove and add” methodology rather than a specific architecture which defines the constructs necessary to allow moving of pieces of the platform around. - + Note: The current AIX implementation does a “remove and add” sequence even when the overall DR operation is a replacement. @@ -405,7 +405,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> between states is initiated by a program action (RTAS functions) provided the conditions for the transition are met. - Note: Relative to + Note: Relative to , physical DRC types are brought in to the “owned by the OS” states either: (1) by the Device Tree at boot time, or (2) by a DLPAR operation, which brings in the logical @@ -416,7 +416,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> OS is done by assigning the logical SLOT DRC above the physical PCI slot, thus giving the following state transitions: state 1, to state 2, to state 3, to state 4, at which time the OS sees the physical slot, sees an IOA in - the physical slot (via + the physical slot (via get-sensor-state (dr-entity-sense) of the physical DRC returning “present”), and then proceeds with the state transitions of: state 5, to state 6, to state 7, to state 8. The reverse of @@ -438,15 +438,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Notes: - In State 5, if empty status is returned from the + In State 5, if empty status is returned from the get-sensor-state dr-entity-sense call, then do not attempt to power-on - Transitions from State 8 to 6 or from State 6 to 5 may fail + Transitions from State 8 to 6 or from State 6 to 5 may fail (set-indicator isolation-state isolate, and get-sensor-state - dr-entity-sense) if the hardware cannot be accessed to control + dr-entity-sense) if the hardware cannot be accessed to control these operations. In this case, the OS may ignore - those errors if the operation is a DLPAR to remove the + those errors if the operation is a DLPAR to remove the hardware. See also the “ibm,ignore-hp-po-fails-for-dlpar” property in . @@ -455,10 +455,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Base DR Option - +
For All DR Options - Platform Requirements - + This section contains the extra requirements placed on the platform for all of the various DR configurations. At this time, there are no provisions made in the DR architecture @@ -474,19 +474,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> possible enhancement for systems that are produced for telephone company applications. . - As mentioned in + As mentioned in , the requirements in this section are not stand-alone requirements; the platform will also need to implement one or more of the specific DR options. - R1-R1--1. - For all DR options: If the - “ibm,configure-connector” - property exists in the + For all DR options: If the + “ibm,configure-connector” + property exists in the /rtas node of the OF device tree, then the platform must meet all of the requirements for the Base DR option (that is, all of the requirements labeled “For all DR options”), and must also @@ -494,19 +494,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> options. - + - R1-R1--2. For all DR options: The platform and OS must adhere to the design and usage restrictions on RTAS routines - defined in + defined in , and any RTAS calls not - specified in - must comply with - Note - and + specified in + must comply with + Note + and . @@ -528,7 +528,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - Reference to + Reference to Note Numbers @@ -547,7 +547,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - Reference to + Reference to Note Numbers @@ -833,7 +833,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Notes: - + These RTAS calls function as specified in this architecture, regardless of the power state @@ -864,7 +864,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The results of the OS changing the power or isolation state of a - Dynamic Reconfigure connector while there is an uncompleted + Dynamic Reconfigure connector while there is an uncompleted ibm,configure-connector operation in progress against that connector are indeterminate. @@ -879,27 +879,27 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The results of the OS issuing these RTAS calls to hardware which is isolated and/or powered off are indeterminate. - + - + - R1-R1--3. For all DR options: If there is Forth code associated with a DR entity, it must not modify the OF device tree properties or - methods unless modifications can be hidden by the + methods unless modifications can be hidden by the ibm,configure-connector RTAS call (that is, where this RTAS routine recognizes the entity and creates the appropriate OF device tree characteristics that would have been created by the Forth code). - + - R1-R1--4. For all DR options: The hardware must protect against @@ -907,9 +907,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> while power is on at the DR connector. - + - R1-R1--5. For all DR options: During a DR operation (including @@ -920,9 +920,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> which the DR entity is being inserted or removed. - + - R1-R1--6. For all DR options: During a DR operation (including @@ -933,9 +933,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> transitions. - + - R1-R1--7. For all DR options: If there are any @@ -946,24 +946,24 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> off. - + - R1-R1--8. For all DR options: A separate visual indicator must be provided for each physical DR connector which can be used for insertion of a DR Entity or which contains a DR entity that can - be removed, and the indicator must be individually controllable via the + be removed, and the indicator must be individually controllable via the set-indicator RTAS call, and must have the capability - to be set to the states as indicated in - and + to be set to the states as indicated in + and . - + - R1-R1--9. For all DR options: @@ -974,9 +974,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> connector. - + - R1-R1--10. For all DR options: If a DR entity requires power to @@ -985,27 +985,27 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> indicate the power state of the DR entity - + - R1-R1--11. For all DR options: The platform must provide any necessary power sequencing between voltages within a power domain during - DR operations (for example, during the + DR operations (for example, during the set-power-level RTAS call). - + - R1-R1--12. For all DR options: If a platform supports DR, then all DR entities must support the full on to off and the off to full on power transitions. - Architecture Note: Requirement + Architecture Note: Requirement is necessary so that the OS can count on the availability of certain RTAS facilities and so that the OS does not use other RTAS facilities when they are not available. This may @@ -1015,9 +1015,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Hardware Implementation Notes: - + - Requirement + Requirement requires careful planning of hardware design and platform structure to assure that no resources critical to RTAS are put into power domains that are powered down as part @@ -1027,13 +1027,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> something is powered off before actually accessing the powered-off hardware. - + - Requirement + Requirement indicates that there cannot be any sharing of indicators between DR connectors. - + In some large systems (for example, systems with many racks of equipment) it may not be possible or convenient to view the individual DR @@ -1048,7 +1048,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> but it is permissible for the indicator to have firmware dependencies. - + @@ -1071,48 +1071,48 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For all DR options: When the firmware passes control to the OS, the DR hardware must be initialized such that all of the DR - connectors which would return “DR entity present” to a + connectors which would return “DR entity present” to a get-sensor-state dr-entity-sense) are fully powered and operational and any DR visual indicators are set to the appropriate - state (on or off) as indicated by + state (on or off) as indicated by . - + - R1-R1--2. For all DR options: After the firmware has passed control to the OS, the state of the DR visual indicators must not change except under the following conditions: - + - As directed to do so by the + As directed to do so by the set-indicator RTAS call. - + Under the condition of a power-fault, in which case the hardware may change the state of the visual indicator to the “off” state if it turns the power off to the slot. - + - + - R1-R1--3. For all DR options: The platforms which have - hierarchical power domains must provide the + hierarchical power domains must provide the “power-domains-tree” property in the OF device tree. @@ -1120,80 +1120,80 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - +
<emphasis role="bold"><literal>“ibm,drc-indexes”</literal></emphasis> Property This property is added for the DR option to specify for each DR connector an index to be passed between the OS and RTAS to identify the DR connector to be operated upon. This property is in the parent node of - the DR connector to which the property applies. See + the DR connector to which the property applies. See for the definition of this property. See for additional information. - R1-R1--1. For all DR options: For each OF device tree node - which supports DR operations on its children, the OF must provide an + which supports DR operations on its children, the OF must provide an “ibm,drc-indexes” property for that node.
- +
<emphasis role="bold"><literal>“ibm,my-drc-index”</literal></emphasis> Property This property is added for the DR option to specify for each node which has a DR connector between it and its parent, the value of the - entry in the + entry in the “ibm,drc-indexes” property for that - connector. This property is used for correlation purposes. See + connector. This property is used for correlation purposes. See for the definition of this property. - R1-R1--1. For all DR options: For each OF device tree node - which has a DR connector between it and its parent, the OF must provide an + which has a DR connector between it and its parent, the OF must provide an “ibm,my-drc-index” property for that node.
- +
<emphasis role="bold"><literal>“ibm,drc-names”</literal></emphasis> Property This property is added for the DR option to specify for each DR - connector a user-readable location code for the connector. See + connector a user-readable location code for the connector. See for the definition of this property. See for additional information. - R1-R1--1. For all DR options: For each OF device tree node - which supports DR operations on its children, the OF must provide an + which supports DR operations on its children, the OF must provide an “ibm,drc-names” property for that node. - + - R1-R1--2. - For all DR options: The content of the + For all DR options: The content of the “ibm,drc-names” property must be of the - format defined in + format defined in . @@ -1274,55 +1274,71 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> more digits and no leading zeroes + + + COPLATFAC + + + location code + + + + + COPLATFUN + + + location code + +
- +
<emphasis role="bold"><literal>“ibm,drc-power-domains”</literal></emphasis> Property This property is added for the DR option to specify for each DR - connector the power domain in which the connector resides. See + connector the power domain in which the connector resides. See for the definition of this property. See for additional information. - R1-R1--1. For all DR options: For each OF device tree node which supports DR operations on its children, the OF - must provide an + must provide an “ibm,drc-power-domains” property for that node. Software Implementation Notes: - + - Software will not call the + Software will not call the set-power-level RTAS call with an invalid power domain number, and for purposes of this call, a power domain number of -1 (a live insert connector) is considered invalid. - + For the case where the power domain is -1 (the live insert case), this does not imply that the connector does not need isolating before the DR operation, only that it does not need to be powered off. - +
- +
<emphasis role="bold"><literal>“ibm,drc-types”</literal></emphasis> Property This property is added for the DR option to specify for each DR - connector a user-readable connector type for the connector. See + connector a user-readable connector type for the connector. See for the definition of this property. See for additional information. @@ -1337,91 +1353,91 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For all DR options: For each OF device tree node - which supports DR operations on its children, the OF must provide an + which supports DR operations on its children, the OF must provide an “ibm,drc-types” property for that node.
- +
<emphasis role="bold"><literal>“ibm,phandle”</literal></emphasis> Property This property is added for the DR option to specify the phandle for - each OF device tree node returned by ibm,configure-connector. See + each OF device tree node returned by ibm,configure-connector. See for the definition of this property. - R1-R1--1. For all DR options: The - ibm,configure-connector RTAS call will include the + ibm,configure-connector RTAS call will include the “ibm,phandle” property in each OF device tree node that it returns. This phandle must be unique and consistent with any phandle visible to an OF client program or any other information - returned by + returned by ibm,configure-connector.
- +
<emphasis role="bold"><literal>“ibm,drc-info”</literal></emphasis> Property - - This property is added to consolidate the information provided by the - “ibm,drc-indexes”, - “ibm,drc-names”, - “ibm,drc-types” and - “ibm,drc-power-domains” properties. + + This property is added to consolidate the information provided by the + “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and + “ibm,drc-power-domains” properties. When present, it replaces those properties. - + - R1-R1--1. - For each OF device tree node which supports DR operations on its children, OF must - provide an “ibm,drc-info” + For each OF device tree node which supports DR operations on its children, OF must + provide an “ibm,drc-info” property for that node. - + - R1-R1--2. - The “ibm,drc-info” property shall only - be present if the Operating System indicates support for this new property definition, - otherwise, the “ibm,drc-indexes”, - “ibm,drc-names”, - “ibm,drc-types” and + The “ibm,drc-info” property shall only + be present if the Operating System indicates support for this new property definition, + otherwise, the “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and “ibm,drc-power-domains” will be present. - + - R1-R1--3. - Following live partition migration the Operating System must be prepared to support - either the “ibm,drc-info” property or the - “ibm,drc-indexes”, - “ibm,drc-names”, - “ibm,drc-types” and - “ibm,drc-power-domains” + Following live partition migration the Operating System must be prepared to support + either the “ibm,drc-info” property or the + “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and + “ibm,drc-power-domains” set of properties. The property or properties presented will based on the capability of the target partition. - +
@@ -1437,14 +1453,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For all DR options: If there is Forth code associated with a DR entity and that Forth code would normally modify the OF device tree properties or methods, then if that entity is - to be supported as a DR entity on a particular platform, the + to be supported as a DR entity on a particular platform, the ibm,configure-connector RTAS call on that platform must recognize that entity and create the appropriate OF device tree characteristics that would have been created by the Forth code. @@ -1453,15 +1469,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- +
<emphasis>set-power-level</emphasis> - This RTAS call is defined in + This RTAS call is defined in . Several additional requirements are placed on this call when the platform implements DR along with PM. This RTAS call is used in DR to power up or power down a DR connector, if necessary (that is, if there is a non-zero power domain - listed for the DR connector in the + listed for the DR connector in the “ibm,drc-indexes” or “ibm,drc-info” property). The input is the power domain and the output is the power level that is @@ -1469,46 +1485,46 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> current power levels are of interest: “full on” and “off.” For sequencing requirements between this RTAS routine and others, - see Requirements - and + see Requirements + and . - R1-R1--1. - For all DR options: the + For all DR options: the set-power-level RTAS call must be implemented as - specified in + specified in and the further requirements of this DR option. - + - R1-R1--2. - For all DR options: The + For all DR options: The set-power-level RTAS call must initiate the operation and return “busy” status for each call until the operation is actually complete. - + - R1-R1--3. For all DR options: If a DR operation involves the user inserting a DR entity, then if the firmware can determine that the inserted entity would cause a system disturbance, then - the + the set-power-level RTAS call must not power up the entity and must return an error status which is unique to that particular - type of error, as indicated in + type of error, as indicated in . @@ -1569,7 +1585,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Hardware Implementation Notes: - + For any DR operation, the firmware could optionally not allow powering up of a DR entity, if the powering up would cause a platform @@ -1578,51 +1594,51 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> capability by a method which is not architected by the DR architecture). - + If PM is not implemented in the platform, then only the “full on” and “off” states need to be implemented for DR and only those two states will be used. - + - Software Implementation Note: The operation of the + Software Implementation Note: The operation of the set-power-level call is not complete at the time of the return from the call if the “busy” status is returned. If it is necessary to know when the operation is complete, the routine should be called with the same parameters until a non-busy status is returned.
- +
<emphasis>get-sensor-state</emphasis> - This RTAS call is defined in + This RTAS call is defined in . This RTAS call will be used in DR to determine if there is something connected to the DR connector. - The - “rtas-sensors” and - “ibm,sensor-<token>” + The + “rtas-sensors” and + “ibm,sensor-<token>” OF properties are not applicable to DR - sensors defined in + sensors defined in . - R1-R1--1. - For all DR options: RTAS must implement the + For all DR options: RTAS must implement the get-sensor-state RTAS call. - + - R1-R1--2. - For all DR options: The sensor values specified in + For all DR options: The sensor values specified in must be implemented as specified in that table. @@ -1673,7 +1689,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Returned for physical DR entities if the connector is available (empty) for an add operation. The DR connector must be allocated to the OS to return this value, otherwise a status - of -3, no such sensor implemented, will be returned from the + of -3, no such sensor implemented, will be returned from the get-sensor-state RTAS call. @@ -1688,7 +1704,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> actually has a DR entity plugged into it. For DR connectors of physical DR entities, the DR connector must be allocated to the OS to return this value, otherwise a status of -3, no such - sensor implemented, will be returned from the + sensor implemented, will be returned from the get-sensor-state RTAS call. For DR connectors of logical DR entities, the DR connector must be allocated to the OS to return this value, otherwise a sensor @@ -1702,7 +1718,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Returned for logical DR entities when the DR entity is not currently available to the OS, but may possibly be made - available to the OS by calling + available to the OS by calling set-indicator with the allocation-state indicator, setting that indicator to usable. @@ -1714,7 +1730,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Returned for logical DR entities when the DR entity is available for exchange in a sparing type operation, in which - case the OS can claim that resource by doing a + case the OS can claim that resource by doing a set-indicator RTAS call with allocation-state set to exchange. @@ -1726,7 +1742,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Returned for logical DR entities when the DR entity can be recovered by the platform and used by the partition - performing a + performing a set-indicator RTAS call with allocation-state set to recover. @@ -1736,19 +1752,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - + - R1-R1--3. For all DR options except the PCI Hot Plug and LRDR options: - If the + If the get-sensor-state call with the dr-entity-sense sensor requires the DR entity to be powered up and/or unisolated to sense the - presence of the DR entity, then the + presence of the DR entity, then the get-sensor-state call must return the error code of - -9000 or -9001, as defined in + -9000 or -9001, as defined in , if the DR entity is powered down or is isolated when the call is made. @@ -1805,25 +1821,25 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> entity unusable). - + - R1-R1--4. For all DR options: The value used for the sensor-index input to the - get-sensor-state RTAS call for the sensors in + get-sensor-state RTAS call for the sensors in must be the index for the - connector, as passed in the + connector, as passed in the “ibm,drc-indexes” or “ibm,drc-info” property. Hardware and Software Implementation Note: The status - introduced in Requirement - is not valid for + introduced in Requirement + is not valid for get-sensor-state calls when trying to sense insertion - status for PCI slots (see Requirement + status for PCI slots (see Requirement ). Architecture Note: DR entity available for recovery @@ -1839,10 +1855,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- +
<emphasis>set-indicator</emphasis> - This RTAS call is defined as shown in + This RTAS call is defined as shown in . This RTAS call is used in DR to transition between isolation states, allocation states, and control DR indicators. In some cases, a state transition fails due to various conditions, @@ -1852,26 +1868,26 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> unisolate the connection between a DR entity and the platform. If physical isolation is indeed required for the DR entity, this RTAS call determines the necessity for isolation, not the calling program. - The - set-indicator allocation-state and + The + set-indicator allocation-state and set-indicator isolation-state are linked. Before - calling + calling set-indicator with isolation-state set to unisolate, the DR entity being unisolated will first need to be allocated to the OS. - If the + If the get-sensor-state call would return a value of DR entity unusable or if it would return an error like -3 for the DR entity, - then the + then the set-indicator isolation-state to unisolate would fail for that DR entity. For sequencing requirements between this RTAS routine and others, - see Requirements - and + see Requirements + and . - A single + A single set-indicator operation for indicator type 9001 may require an extended period of time for execution. Following the - initiation of the hardware operation, if the + initiation of the hardware operation, if the set-indicator call returns prior to successful completion of the operation, the call will return either a status code of -2 or 990x. A status code of -2 indicates that RTAS may be capable of @@ -1886,20 +1902,20 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> indicates which DR indicators are used with which DR connector types. - The - “rtas-indicators” and - “ibm,indicator-<token>” + The + “rtas-indicators” and + “ibm,indicator-<token>” OF properties are not applicable to DR - indicators defined in + indicators defined in . - R1-R1--1. For all DR options: The indicator state values - specified in + specified in must be implemented as specified in that table. @@ -1964,14 +1980,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> firmware, and in the case of a physical DR entity like a PCI IOA, logically disconnects the DR entity from the platform (for example, from the PCI bus). Unisolate refers to the DR action - to logically connect the entity. Before + to logically connect the entity. Before set-indicator isolation-state to unisolate, the DR entity being unisolated must first be allocated to the - OS. If the + OS. If the get-sensor-state call with the dr-entity-sense token would return a value of DR entity unusable or if it would return an error like -3 for the DR - entity, then the + entity, then the set-indicator isolation-state to unisolate must fail for that DR entity. @@ -1997,8 +2013,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This indicator must be implemented for DR connectors for physical DR entities. If the DR indicators exist for the DR connector, then they are used to indicate the state of the DR - connector to the user. Usage of these states are as defined in - and + connector to the user. Usage of these states are as defined in + and . @@ -2024,7 +2040,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> to the OS. The initial allocation state of a connector is established based upon the initial allocation of resources to the OS image. Subsequently, an OS may request a change of - allocation state by use of the + allocation state by use of the set-indicator with allocation-state token. If the transition to the usable state is not possible the -3 (no such indicator implemented) status is returned. @@ -2035,95 +2051,95 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - + - R1-R1--2. For all DR options: - The value used for the indicator-index input to the - set-indicator RTAS call for the indicators in + The value used for the indicator-index input to the + set-indicator RTAS call for the indicators in must be the index for the - connector, as passed in the + connector, as passed in the “ibm,drc-indexes” or “ibm,drc-info” property. - + - R1-R1--3. - For all DR options: The + For all DR options: The set-indicator call must return a -2 status, or optionally for indicator type 9001 the 990x status, for each call until - the operation is complete; where the 990x status is defined in + the operation is complete; where the 990x status is defined in . - + - R1-R1--4. For all DR options: If this is a DR operation that involves the user inserting a DR entity, then if the firmware can determine that the inserted entity would cause a system disturbance, then - the + the set-indicator RTAS call must not unisolate the entity and must return an error status which is unique to the particular error. - + - R1-R1--5. - For all DR options: If the + For all DR options: If the set-indicator index refers to a connector that would - return a “DR entity unusable” status (2) to the - get-sensor dr-entity-sense token, the + return a “DR entity unusable” status (2) to the + get-sensor dr-entity-sense token, the set-indicator RTAS return code must be “No such - indicator implemented” (-3), except in response to a successful + indicator implemented” (-3), except in response to a successful set-indicator allocation state usable. - + - R1-R1--6. For all DR options combined with the LPAR option: The - RTAS + RTAS set-indicator specifying unusable allocation-state of a DR connector must unmap the resource from the partition’s Page Frame Table(s) and, as appropriate, its Translation Control Entry tables. - + - R1-R1--7. For all DR options combined with the LPAR option: The - successful completion of the RTAS + successful completion of the RTAS set-indicator specifying usable allocation-state of a DR connector must allow subsequent mapping of the resource as appropriate within the partition’s Page Frame Table(s) and/or its Translation Control Entry tables. - Software Implementation Note: The operation of the + Software Implementation Note: The operation of the set-indicator call is not complete at the time of the return from the call if the “busy” status is returned. If it is necessary to know when the operation is complete, the routine should be called with the same parameters until a non-busy status is returned. - Hardware and Software Implementation Note: The + Hardware and Software Implementation Note: The set-indicator (isolation-state) call is used to clear - RTAS internal tables regarding this device. The + RTAS internal tables regarding this device. The ibm,configure-connector RTAS routine will need to be called before using the entities below this connector, even if power was never removed from an entity while it was in the isolated state. @@ -2131,42 +2147,42 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- +
<emphasis>ibm,configure-connector</emphasis> RTAS Call - The RTAS function + The RTAS function ibm,configure-connector is a new RTAS call introduced by DR and is used to configure a DR entity after it has been added by - either an add or replace operation. It is expected that the + either an add or replace operation. It is expected that the ibm,configure-connector RTAS routine will have to be called several times to complete the configuration of a dynamic reconfiguration connector, due to the time required to complete the entire configuration process. The work area contains the intermediate state that RTAS needs to retain between calls. The work area consists of 4096 byte pages of real storage on 4096 byte boundaries which can be - increased by one page on each call. The OS may interleave calls to + increased by one page on each call. The OS may interleave calls to ibm,configure-connector for different dynamic reconfiguration connectors, however, a separate work area will be associated with each dynamic reconfiguration connector which is actively being configured. Other standard RTAS locking rules apply. - The properties generated by the + The properties generated by the ibm,configure-connector call are dependent on the type of DR entities. For a list of properties generated, see the RTAS Requirements section for each specific DR option. For example, for a list - of properties generated for PCI Hot Plug, see + of properties generated for PCI Hot Plug, see . For sequencing requirements between this RTAS routine and others, - see Requirement + see Requirement . - R1-R1--1. - For all DR options: The RTAS function + For all DR options: The RTAS function ibm,configure-connector must be implemented and must - implement the argument call buffer defined by + implement the argument call buffer defined by . @@ -2205,7 +2221,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - Token for + Token for ibm,configure-connector @@ -2281,14 +2297,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- + - R1-R1--2. For all DR options: On the first call of a dynamic reconfiguration sequence, the one page work area must be initialized by - the OS as in + the OS as in . @@ -2317,7 +2333,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 0 - entry from the + entry from the “ibm,drc-indexes” or “ibm,drc-info” property for the connector to configure @@ -2335,15 +2351,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Architecture Note: The entry offset in + Architecture Note: The entry offset in is either four bytes or eight bytes depending on whether RTAS was instantiated in 32-bit or 64-bit mode, respectively. - + - R1-R1--3. For all DR options: On all subsequent calls of the @@ -2351,12 +2367,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> last return from RTAS. - + - R1-R1--4. - For all DR options: The + For all DR options: The ibm,configure-connector RTAS call must update any necessary RTAS configuration state based upon the configuration changes effected through the specified DR connector. @@ -2373,23 +2389,23 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> reported devices remain unconfigured and unusable. RTAS internal data structures (outside of the work area) are not updated until the call which returns “configuration complete” status. A subsequent - sequence of calls to - ibm,configure-connector with the same entry from the + sequence of calls to + ibm,configure-connector with the same entry from the “ibm,drc-indexes” or “ibm,drc-info” property will restart the configuration of devices which were not completely configured. - If the index from + If the index from “ibm,drc-indexes” or “ibm,drc-info” refers to a connector - that would return an “DR entity unusable” status (2) to the - get-sensor RTAS call with dr-entity-sense token, the + that would return an “DR entity unusable” status (2) to the + get-sensor RTAS call with dr-entity-sense token, the ibm,configure-connector RTAS call for that index immediately returns “-9003: Cannot configure - Logical DR connector unusable” on the first call without any configuration action taken on the DR connector. A dynamic reconfiguration connector may attach several sibling OF device tree architected devices. Each such device may be the parent of - one or more device sub-trees. The + one or more device sub-trees. The ibm,configure-connector RTAS routine configures and reports the entire sub-tree of devices rooted in previously unconfigured architected devices found below the connector whose index is specified in @@ -2397,14 +2413,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> an empty or unowned dynamic reconfiguration connector; where unowned refers to a DR connector that would return a DR entity unusable, a DR entity available for exchange, or a DR entity available for entity - available for recovery value, for a + available for recovery value, for a get-sensor dr-entity-sense sensor. Configuration proceeds in a depth first order. - If the + If the ibm,configure-connector RTAS routine returns with the “call again” or 990x status, configuration is proceeding but had to be suspended to maintain the short execution time requirement of - RTAS routines. No results are available. The OS should call the + RTAS routines. No results are available. The OS should call the ibm,configure-connector RTAS routine passing back the work area unmodified at a later time to continue the configuration process. @@ -2418,23 +2434,23 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> appropriate system documentation relative to the DR Entity that they are trying to insert into the system. The “need more memory” status code, is similar in - semantics to the “call again” status. However, on the next + semantics to the “call again” status. However, on the next ibm,configure-connector call, the OS will supply, via - the + the Memory extent parameter, the address of another page of memory for RTAS to add to the work area in order for configuration to - continue. On all other calls to - ibm,configure-connector the contents of the + continue. On all other calls to + ibm,configure-connector the contents of the Memory extent parameter should be 0. It is the responsibility of the OS to recover all work area memory after a sequence - of + of ibm,configure-connector calls is completed. Software Implementation Note: The OS may allocate the work area from contiguous virtual space and pass individual discontiguous - real pages to + real pages to ibm,configure-connector as needed. - If the + If the ibm,configure-connector RTAS routine returns either the “next sibling” or “next child” status codes, configuration has detected an architected OF device tree device, and is @@ -2453,13 +2469,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> entry offset 4 contains an offset within the first page of the work area to the value of the property. - Architecture Note: The + Architecture Note: The ibm,configure-connector RTAS routine returns those applicable properties that can be determined without interpreting any FCode ROM which is associated with the IOA. Additionally, it is permissible for this RTAS call to be aware of various specific IOAs and emulate the action of any FCode associated with the IOA. - If the + If the ibm,configure-connector RTAS routine returns the “previous parent” status code, it has come to the end of the string of siblings, and will back up the tree one level following its @@ -2468,7 +2484,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Software Implementation Notes: - + Any attempts to configure an already configured connector or one in progress of being configured will produce unpredictable @@ -2477,15 +2493,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The software will put the DR entity in the full on power state - before issuing the + before issuing the ibm,configure-connector RTAS call to configure the DR entity. - +
- +
For All DR Options - OS Requirements @@ -2495,16 +2511,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> DR Visual indicator usage will be as indicated in the following requirement, in order to provide for a consistent user interface across platforms. Information on implementation dependent aspects of the DR - indicators can be found in + indicators can be found in . - R1-R1--1. For all DR options: The visual indicators must be - used as defined in + used as defined in . @@ -2538,9 +2554,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The DR connector is inactive and entity may be removed or added without system disruption. For DR entities that require - power off at the connector, then the caller of + power off at the connector, then the caller of set-indicator must turn power off prior to - setting the indicator to this state. See also + setting the indicator to this state. See also . @@ -2552,7 +2568,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This indicator state is used to allow the user to identify the physical location of the DR connector. This state may map to the same visual state (for example, blink rate) as - the Action state, or may map to a different state. See also + the Action state, or may map to a different state. See also . @@ -2564,7 +2580,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Used to indicate to the user the DR connector on which the user is to perform the current DR operation. This state may map to the same visual state (for example, blink rate) as the - Identify state, or may map to a different state. See also + Identify state, or may map to a different state. See also . @@ -2574,7 +2590,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The DR connector is active and entity removal may disrupt - system operation. See also + system operation. See also . @@ -2582,24 +2598,24 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- +
Other Requirements - R1-R1--1. For all DR options: The OS must detect hierarchical - power domains (as specified in the + power domains (as specified in the “power-domains-tree” property) and must handle those properly during a DR operation. - + - R1-R1--2. For all DR options: @@ -2608,9 +2624,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> following order: - + - If the power domain is not 0, then call + If the power domain is not 0, then call set-power-level @@ -2622,12 +2638,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> ibm,configure-connector - + - + - R1-R1--3. For all DR options: @@ -2635,26 +2651,26 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> entity offline, the OS must issue the following RTAS calls in the following order: - + set-indicator with the isolation-state token and a state value of isolate) - If the power domain is not 0, then call + If the power domain is not 0, then call set-power-level - + - + - R1-R1--4. When bringing a DR entity online that - utilizes TCEs (see + utilizes TCEs (see ), the OS must initialize the DR entity's TCEs. @@ -2664,14 +2680,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- +
PCI Hot Plug DR Option This section will develop the requirements over and beyond the base DR option requirements, that are unique to being able to perform DR operations on PCI plug-in cards that do not share power domains with other PCI plug-in cards. - +
PCI Hot Plug DR - Platform Requirements A method will be provided to isolate the plug-in card (power and @@ -2687,7 +2703,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For the PCI Hot Plug DR option: All platform @@ -2695,27 +2711,27 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> ). - + - R1-R1--2. For the PCI Hot Plug DR option: All PCI requirements must be met (for example, timing rules, power slew rates, etc.) as - specified in the appropriate PCI specifications, and in the + specified in the appropriate PCI specifications, and in the . - + - R1-R1--3. For the PCI Hot Plug DR option: The hardware must provide two indicators per PCI Hot Plug slot, and all the following must be true: - + One indicator must be green and the platform must use the indicator to indicate the power state of the PCI Hot Plug slot, turning @@ -2726,16 +2742,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The other indicator must be amber and must be controllable by RTAS, separately from all other indicators, and must be used as a slot - Identify indicator, as defined in + Identify indicator, as defined in . - + - + - R1-R1--4. For the PCI Hot Plug DR option: @@ -2745,9 +2761,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> in the platform. - + - R1-R1--5. For the PCI Hot Plug DR option: @@ -2758,9 +2774,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> the plug-in card. - + - R1-R1--6. For the PCI Hot Plug DR option: @@ -2773,9 +2789,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> removal. - + - R1-R1--7. For the PCI Hot Plug option: @@ -2785,15 +2801,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> would result in improper operation of the system. - + - R1-R1--8. For the PCI Hot Plug option: For each PCI Hot Plug slot which will accept only 32-bit (data width) plug-in cards, the platform must: - + Accommodate plug-in cards requiring up to 64 MB of PCI Memory Space and 64 KB of PCI I/O space @@ -2804,19 +2820,19 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> map simultaneously and at all times at least 128 MB of PCI Memory space for the slot. - + - + - R1-R1--9. For the PCI Hot Plug option: Each PCI Hot Plug slot which will accept 64-bit (data width) plug-in cards, the platform must: - + Accommodate plug-in cards requiring up to 128 MB of PCI Memory Space and 64 KB of PCI I/O space @@ -2827,24 +2843,24 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> map simultaneously and at all times at least 256 MB of PCI Memory space for the slot. - + - + - R1-R1--10. For the PCI Hot Plug option with PCI Express: The power and isolation controls must be implemented by use of the PCI - Standard Hot-Plug Controller (see + Standard Hot-Plug Controller (see ). - + - R1-R1--11. For the PCI Hot Plug option with PCI Express: If a @@ -2853,7 +2869,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Hardware implementation Notes: - + Surge current protection on the planar is one way to provide the required protection against damage to components if an entity is removed @@ -2876,25 +2892,25 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> It is recommended that the control of the indicators required by - Requirement + Requirement be via the PCI Standard Hot - Plug Controller (see + Plug Controller (see ). - +
- +
PCI Hot Plug DR - Boot Time Firmware Requirements - R1-R1--1. For the PCI Hot Plug DR option: All OF requirements @@ -2902,21 +2918,21 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> ). - + - R1-R1--2. For the PCI Hot Plug DR option: The OF must only - generate the + generate the “clock-frequency” OF property for PCI bridge nodes which cannot change bus clock frequency during a PCI Hot Plug operation. - + - R1-R1--3. For the PCI Hot Plug DR option: The OF must set the @@ -2943,7 +2959,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For the PCI Hot Plug DR option: All RTAS requirements @@ -2951,12 +2967,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> ). - + - R1-R1--2. - For the PCI Hot Plug DR option: The + For the PCI Hot Plug DR option: The set-indicator RTAS call with a indicator type of isolation-state and a state value of unisolate (1) must not return a “success” status until any IOA on a plug-in card inserted @@ -2964,12 +2980,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> return a “success” status if the PCI slot is empty. - + - R1-R1--3. - For the PCI Hot Plug DR option: The + For the PCI Hot Plug DR option: The ibm,configure-connector RTAS call must initialize the PCI configuration registers and platform to the same values as at boot time. @@ -2984,7 +3000,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> replace the configuration information into the new IOA. PCI I/O sub-systems architecturally consist of two classes of devices, bus bridges (Processor Host Bridges (PHBs), PCI to PCI Bridges, - and PCI Express switches and bridges) and IOAs. The support that + and PCI Express switches and bridges) and IOAs. The support that ibm,configure-connector provides for these two classes is different. For Bus Bridges, firmware will totally configure the bridge so that @@ -2995,7 +3011,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> reported are the same as provided by the boot time firmware. For PCI plug-in cards, the support is significantly less; it is essentially the functionality specified in section 2.5 FCode Evaluation - Semantics of the + Semantics of the . However, the configuration proceeds as if all devices do not have an expansion ROM since the RTAS code does not attempt to determine if an FCode ROM is present nor @@ -3010,26 +3026,26 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> ibm,configure-connector will not generate it. shows what PCI OF properties - can be expected to be returned from the + can be expected to be returned from the ibm,configure-connector call for PCI Hot Plug - operations and + operations and shows some which can be expected to not be returned. - + - R1-R1--4. - For the PCI Hot Plug DR option: The + For the PCI Hot Plug DR option: The ibm,configure-connector RTAS call when used for PCI - IOAs must return the properties named in + IOAs must return the properties named in except as indicated in the Present?/Source column. - PCI Property Names which will be Generated by + <title>PCI Property Names which will be Generated by <emphasis>ibm,configure-connector</emphasis> @@ -3277,7 +3293,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Always present for sub-systems and for PCI IOAs which - follow the PCI VPD proposed standard. See + follow the PCI VPD proposed standard. See and note to see the effect of using different PCI versions. @@ -3290,7 +3306,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - For bridges, always present with a value of + For bridges, always present with a value of “PCI” otherwise not present. @@ -3311,14 +3327,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
is a non-exhaustive list of - common properties that may not be generated by RTAS + common properties that may not be generated by RTAS ibm,configure connector for a PCI IOA. Also, the - concept of a phandle does not apply to nodes reported by + concept of a phandle does not apply to nodes reported by ibm,configure-connector. Non-exhaustive list of PCI properties that may not be - generated by + generated by <emphasis>ibm,configure connector</emphasis> @@ -3465,22 +3481,22 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Architecture Note: Without + Architecture Note: Without “device_type” and other properties, the OS cannot append an IOA added via DR to the boot list for use during the next boot. - + - R1-R1--5. - For the PCI Hot Plug option: When + For the PCI Hot Plug option: When ibm,configure-connector RTAS call returns to the caller, if the device driver(s) for any IOA(s) configured as part of the call are EEH unaware (that is may produce data integrity exposures due to - an EEH stopped state) or if they may be EEH unaware, then the + an EEH stopped state) or if they may be EEH unaware, then the ibm,configure-connector call must disable EEH prior to returning to the caller. @@ -3489,13 +3505,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> state, only recognize the all-1's condition 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 + turn off interrupts (using the ibm,set-int-off RTAS call) in order to make sure that any (unserviceable) interrupts from the IOA do not affect the system. Note that this is the same device driver support needed to protect against an IOA dying or against a no-DEVSEL type error (which may or may not be the result of an IOA that has died). Note that if all-1’s - data may be valid, the + data may be valid, the ibm,read-slot-reset-state2 RTAS call should be used to discover the true EEH state of the device. @@ -3508,7 +3524,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For the PCI Hot Plug DR option: All OS requirements @@ -3529,7 +3545,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> image(s). The Logical Resource Dynamic Reconfiguration option provides the means for providing capacity on demand to the running OS and provides the capability for the platform to make available spare parts (for example, - CPUs) to replace failing ones (called + CPUs) to replace failing ones (called sparing operations). Combined with the LPAR option, platforms can move resources between partitions without rebooting the partitions’ OS images. @@ -3548,11 +3564,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> fewer than that currently installed. In other cases, such as memory regions in a LPARed system, the number may be limited to the amount of memory that can be supported without resizing the cpu page frame table. The OS may use - the + the get-sensor-state RTAS call with the dr-entity-sense token to determine if a given drc-index refers to a connector that is currently usable for DR operations. If the connector is not currently - usable the return state is “DR entity unusable” (2). A + usable the return state is “DR entity unusable” (2). A set-indicator (isolation state) RTAS call to an unusable connector or (dr-indicator) to any logical resource connector results in a “No such indicator implemented” return @@ -3562,14 +3578,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> In this model, a DR entity state is changed from unusable to usable only by firmware in response to HMC requests to explicitly move the allocation of the resource between partitions. In the second model, certain resources may - “float” between cooperating partitions, a partition issues a + “float” between cooperating partitions, a partition issues a set-indicator (allocation state usable) RTAS call and if the resource is free, the firmware assigns the resource to the - requesting partition and returns the success status. + requesting partition and returns the success status. Set-indicator returns the code “no-such-indicator” if either the resource is not free, or the platform is operating in the first model. To return a resource to the - platform firmware, the OS issues a + platform firmware, the OS issues a set-indicator (allocation state unusable) RTAS call for the resource’s DR connector. @@ -3580,7 +3596,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For the LRDR option: The hardware must provide the @@ -3602,9 +3618,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> an OS, independent of whether or not LRDR is implemented. - + - R1-R1--2. For the LRDR option: @@ -3613,7 +3629,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> (for example, as part of an ibm,configure-connector operation), must be functionally transparent to the software, except that PCI plug-in cards that are plugged into a PCI Hot Plug DR connector do not need to be - powered on before the + powered on before the ibm,configure-connector call for a logical SLOT DR connector returns to the caller. @@ -3621,7 +3637,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> into a DR connector will not be configured as part of an ibm,configure-connector operation on a logical DR connector of type SLOT above the plug-in card (see section 17.6.3.3 ibm,configure-connector). - However, Requirement + However, Requirement does require a PCI IOA which is not plugged in to a PCI Hot Plug DR connector (for example, soldered on the planar) be powered up and configured as a result of an @@ -3667,7 +3683,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - As defined in + As defined in . @@ -3678,7 +3694,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - As defined in + As defined in . @@ -3689,9 +3705,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - As defined in + As defined in . - Note: + Note: This name allows for correlation between the OS and HMC user interfaces. @@ -3705,7 +3721,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Logical Resource connectors are defined to be “hot - pluggable” having a domain value of -1 per definition in + pluggable” having a domain value of -1 per definition in . @@ -3718,7 +3734,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Shall be one of the values “CPU”, “MEM”, “PHB”, or “SLOT” as - defined in + defined in . @@ -3729,7 +3745,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - As defined in + As defined in . @@ -3739,7 +3755,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. For the LRDR option: All platform requirements of the @@ -3747,44 +3763,44 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> ). - + - R1-R1--2. - For the LRDR option: The + For the LRDR option: The /cpus OF device tree node must include either the “ibm,drc-info” - property or the following four properties: - “ibm,drc-types”, - “ibm,drc-names”, - “ibm,drc-indexes” and - “ibm,drc-power-domains”. - The drc-type must be type CPU, and the drc-power-domain must have the value -1. The + property or the following four properties: + “ibm,drc-types”, + “ibm,drc-names”, + “ibm,drc-indexes” and + “ibm,drc-power-domains”. + The drc-type must be type CPU, and the drc-power-domain must have the value -1. The property or properties must contain entries for each potentially supported dynamically reconfigurable processor. - + - R1-R1--3. For the LRDR option: The root node of the OF device - tree must include - ither the “ibm,drc-info” - property or the following four properties: - “ibm,drc-indexes”, - “ibm,drc-names”, - “ibm,drc-types” and - “ibm,drc-power-domains”. + tree must include + ither the “ibm,drc-info” + property or the following four properties: + “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and + “ibm,drc-power-domains”. The drc-type must be type MEM and the drc-power-domain must have the value -1. - The property or properties must contain entries for each potentially supported dynamically + The property or properties must contain entries for each potentially supported dynamically reconfigurable memory region. - + - R1-R1--4. For the LRDR option: The root node of the OF device @@ -3793,62 +3809,62 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> (reg value 0). - + - R1-R1--5. For the LRDR option: The root node of the OF device - tree must include - either the “ibm,drc-info” - property or the following four properties: - “ibm,drc-indexes”, - “ibm,drc-names”, - “ibm,drc-types” and - “ibm,drc-power-domains”. - The drc-type must be type PHB, and the drc-power-domain must have the value -1. - The property or properties must contain entries for each potentially supported dynamically + tree must include + either the “ibm,drc-info” + property or the following four properties: + “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and + “ibm,drc-power-domains”. + The drc-type must be type PHB, and the drc-power-domain must have the value -1. + The property or properties must contain entries for each potentially supported dynamically reconfigurable PHB. - + - R1-R1--6. - For the LRDR option: The + For the LRDR option: The /pci OF device tree node representing a PHB must - include - either the “ibm,drc-info” - property or the following four properties: - “ibm,drc-indexes”, - “ibm,drc-names”, - “ibm,drc-types” and - “ibm,drc-power-domains”. - The drc-type must be type SLOT, and the drc-power-domain must have the value -1. - The property or properties must contain entries for each potentially supported dynamically + include + either the “ibm,drc-info” + property or the following four properties: + “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and + “ibm,drc-power-domains”. + The drc-type must be type SLOT, and the drc-power-domain must have the value -1. + The property or properties must contain entries for each potentially supported dynamically reconfigurable PCI SLOT. - + - R1-R1--7. For the LRDR option: platforms must implement the - allocation-state indicator 9003, as defined in + allocation-state indicator 9003, as defined in . - + - R1-R1--8. - For the LRDR option: For memory LRDR, the + For the LRDR option: For memory LRDR, the “ibm,lrdr-capacity” property must be - included in the - /rtas node of the partition device tree (see + included in the + /rtas node of the partition device tree (see ). @@ -3858,16 +3874,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Architectural Intent -- Logical DR Sequences: This architecture is designed to support the logical DR sequences - specified in the following sections. See also + specified in the following sections. See also .
Acquire Logical Resource from Resource Pool - + The OS responds to some stimuli (command, workload manager, HMC, - etc.) to acquire the resource, perhaps using the + etc.) to acquire the resource, perhaps using the “ibm,drc-names” value as a reference if a human interface is involved. @@ -3875,22 +3891,22 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The OS determines if the resource is usable: - - + + - OS uses + OS uses get-sensor-state (dr-entity-sense) to determine the state of the DR connector - If the state is “unusable” the OS issues + If the state is “unusable” the OS issues set-indicator (allocation-state, usable) to attempt to allocate the resource. Similarly, if the state is “available for - exchange” the OS issues + exchange” the OS issues set-indicator (allocation-state, exchange) to attempt to allocate the resource, and if the state is “available for - recovery” the OS issues + recovery” the OS issues set-indicator (allocation-state, recover) to attempt to allocate the resource. @@ -3900,15 +3916,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> requester. If successful, this is the point where the resource is allocated to the OS. - + Continue with DR operation. - + - The OS unisolates the resource via + The OS unisolates the resource via set-indicator (isolation-state, unisolate). This is the point where the OS takes ownership of the resource from the platform firmware and the firmware removes the resource from its resource @@ -3916,67 +3932,67 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - The OS configures the resource using + The OS configures the resource using ibm,configure-connector RTAS. The OS incorporates the resource into its resource pool. - + - If the resource is a processor, the OS must use the + If the resource is a processor, the OS must use the start-cpu RTAS call to move the processor from the - stopped state (at the end of the + stopped state (at the end of the ibm,configure-connector) to the running state. - + The OS returns status of operation to the requester. - + The OS notifies requesting entity of the OS state relative to the resource acquisition. - +
Release Logical Resource - + Some entity (System administrator commanding from the HMC, a - workload manager, etc.) requests the OS to release the resource using the + workload manager, etc.) requests the OS to release the resource using the “ibm,drc-names” value as a reference. - + The OS attempts to stop using logical resource. - + - If the resource is a processor, the OS calls the + If the resource is a processor, the OS calls the stop-self RTAS call then waits for the processor to - enter the stopped state using the RTAS + enter the stopped state using the RTAS query-cpu-stopped-state call. - The OS isolates the resource via + The OS isolates the resource via set-indicator (isolation-state, isolate). Unless the isolated resource was the partition’s last - processor, the OS deallocates the resource via + processor, the OS deallocates the resource via set-indicator (allocation-state, unusable). This is the point where the platform firmware takes ownership of the resource from the OS. That is, the OS removes the resource from its resource pool @@ -3988,11 +4004,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> The OS returns status of operation to the requester. - + - The OS unallocates the resource by + The OS unallocates the resource by set-indicator (allocation-state, unusable). @@ -4005,7 +4021,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Any needed hardware removal is handled by HMC/SPC. - +
@@ -4022,7 +4038,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
Isolation of CPUs - The isolation of a CPU, in all cases, is preceded by the + The isolation of a CPU, in all cases, is preceded by the stop-self RTAS function for all processor threads, and the OS insures that all the CPU’s threads are in the RTAS stopped state prior to isolating the CPU. Isolation of a processor that @@ -4033,22 +4049,22 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. - For the LRDR option: Prior to issuing the RTAS + For the LRDR option: Prior to issuing the RTAS set-indicator specifying isolate isolation-state of a CPU DR connector type, all the CPU threads must be in the RTAS stopped state. - + - R1-R1--2. For the LRDR option: Stopping of the last processor - thread of a LPAR partition with the + thread of a LPAR partition with the stop-self RTAS function, must kill the partition, with ownership of all partition resources reverting to the platform firmware. @@ -4073,25 +4089,25 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> option is combined with the LPAR option, the hypervisor ensures that the addresses of the MEM region being isolated are unmapped from both the PFT and TCE tables before successfully completing the isolation of the MEM - region. If any valid mappings are found, the RTAS + region. If any valid mappings are found, the RTAS set-indicator (isolation-state) does not change the - isolation-state and returns with a + isolation-state and returns with a Status-9001 (Valid outstanding translation). - R1-R1--1. - For the LRDR option: The caller of the RTAS + For the LRDR option: The caller of the RTAS set-indicator specifying isolate isolation-state of a MEM DR connector type must not be within the region being isolated. - + - R1-R1--2. For the LRDR option combined with the LPAR option: @@ -4099,7 +4115,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> MEM DR connector type must check that the region is unmapped from both the partition’s Page Frame Table(s) and any Translation Control Entries that would reference the memory, else the RTAS routine must - return with a status of + return with a status of Status-9001 (Valid outstanding translation) and the isolation-state is not changed. @@ -4108,13 +4124,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Implementation Note: The algorithm chosen for - implementing Requirement + implementing Requirement depends upon the expected frequency of isolation events. For RAS reasons, they should be seldom. For load balancing, they may be far more frequent. These methods are briefly described here: - + First pull the corresponding logical address from the partition’s valid space so setting new translations to the logical @@ -4124,15 +4140,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> particular logical address range. The PFT/TCE table search may be long, however, it is only done at isolation time. - + The use count method must be maintained for each add and remove of an address translation with the corresponding accessing of a use count based upon the physical real address of the memory block. - +
- +
Isolation of PHBs and Slots An isolation of a PHB naturally disconnects the OS image from any @@ -4141,48 +4157,48 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> complexity of gracefully managing multi-level isolation, isolation is restricted to only “leaf” DR connectors, that is connectors that have no unisolated or usable DR connectors below them. That is, for - logical DR connectors below the connector being isolated, a + logical DR connectors below the connector being isolated, a get-sensor-state dr-entity-sense needs to return an unusable (2) and for physical DR connectors below the connector being isolated, the DR entity needs to be isolated first via set-indicator (isolation-state, isolate). The OS is responsible for removing all virtual address mappings to the address - range associated with a logical I/O SLOT before making the RTAS + range associated with a logical I/O SLOT before making the RTAS set-indicator (isolation-state) call that isolates the SLOT. When the LRDR option is combined with the LPAR option, the hypervisor ensures that the addresses associated with the logical SLOT being isolated are unmapped from both the PFT and TCE tables before successfully completing the isolation of the SLOT connector. If any valid - mappings are found, the RTAS + mappings are found, the RTAS set-indicator (isolation-state) does not change the - isolation-state and returns with a + isolation-state and returns with a Status-9001 (Valid outstanding translation). - R1-R1--1. - For all LRDR options: If a request to + For all LRDR options: If a request to set-indicator (isolation-state, isolate) would result in the isolation of one or more other DR connectors which are currently - unisolated or usable, then the + unisolated or usable, then the set-indicator RTAS must fail with a return code of “Multi-level isolation error” (-9000). - + - R1-R1--2. For the LRDR option combined with the LPAR - option: The RTAS + option: The RTAS set-indicator specifying isolate isolation-state of a SLOT DR connector type must check that the IOA address range associated with the slot is unmapped from both the partition’s Page Frame Table(s) and any Translation Control Entries that would reference those - locations, else the RTAS routine must return with a + locations, else the RTAS routine must return with a Status-9001 (Valid outstanding translation) and the isolation-state is not changed. @@ -4192,6 +4208,52 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
+
+ Isolation of Coherent Platform Facilities + + Isolation of a Coherent Platform Facility (COPLATFAC) disconnects the OS + image from any of the DR connectors downstream (Coherent Platform Functions or + COPLATFUN) of the Coherent Platform Facility. To avoid the complex- ity of + gracefully managing multi-level isolation, isolation is restricted to only + “leaf” DR connectors, that is connectors that have no unisolated or usable DR + connectors below them. All COPLATFUN connectors must return unusable state (2) + during get-sensor-state before a COPLATFAC can be isolated, this is done through + set-indicator (isolation-state, isolate). The OS is responsible for removing all + memory mappings and detaching all processes potentially in use by co- herent + platform functions. If valid mappings or processes are found, the set-indicator + does not change the isolation state and returns with a Status -9001 (Valid + outstanding translation). + + + + R1--1. + + For all LRDR options: If a + request to set-indicator (isolation-state, isolate) + would result in the isolation of one or more other DR connectors + which are currently unisolated or usable, then the + set-indicator RTAS must fail with a return code of + “Multi-level isolation error” (-9000). + + + + + R1--2. + + For the LRDR option combined with the LPAR + option: The RTAS set-indicator specifying + isolate isolation-state of a COPLATFUN DR connector type must check that + all processes associated with the function are detached, else the RTAS + routine must return with a Status -9001 (Valid outstanding translation) + and the isolation-state is not changed. + + + + +
+
<emphasis>set-indicator</emphasis> (dr-indicator) Logical connectors do not have associated dr-indicators (token @@ -4201,10 +4263,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. - For all LRDR options: The calling of + For all LRDR options: The calling of set-indicator with a token value of 9002 (dr-indicator) and an index representing a logical connector must fail with a return code of “No such indicator implemented” @@ -4216,18 +4278,18 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<emphasis>ibm,configure-connector</emphasis> - The + The ibm,configure-connector RTAS call is used to return to the OS the device tree nodes and properties associated with the newly un-isolated logical resources and configure them for use. - The + The ibm,configure-connector RTAS call used against a logical DR connector can encounter other logical DR connectors or physical DR connectors below it in the tree. If a logical connector is - encountered below a logical connector that is being configured, the + encountered below a logical connector that is being configured, the ibm,configure-connector RTAS call will not configure the sub-tree, if it is not owned by the OS (where owned refers to a DR - connector that would return a DR entity usable, for a + connector that would return a DR entity usable, for a get-sensor dr-entity-sense sensor). If a physical connector is encountered, then the sub-tree below the physical connector may or may not be configured, depending on the implementation. @@ -4244,38 +4306,38 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - R1-R1--1. - For all LRDR options: If a request to + For all LRDR options: If a request to ibm,configure-connector specifies a connector that is - isolated, + isolated, ibm,configure-connector must immediately return configuration complete. - + - R1-R1--2. For all LRDR options: If the connector index refers to a connector that would return a “DR entity unusable” status (2), “DR entity available for exchange” status (3), or - “DR entity available for recovery” status (4) to the - get-sensor dr-entity-sense token, the + “DR entity available for recovery” status (4) to the + get-sensor dr-entity-sense token, the ibm,configure-connector RTAS call must return “-9003: Cannot configure - Logical DR connector unusable, available for exchange, or available for recovery” on the first call without any configuration action taken on the DR connector. - + - R1-R1--3. - For all LRDR options: If a request to + For all LRDR options: If a request to ibm,configure-connector specifies a connector of type CPU, the returned sub-tree must consist of the specific @@ -4286,41 +4348,41 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> Implementation Note: Future platforms that support concurrent maintenance of caches, will require that high level cache - nodes (L2, L3 etc.) are added by + nodes (L2, L3 etc.) are added by ibm,configure-connector such that their properties can change as new/repaired hardware is added to the platform. Therefore, it is the OS's responsibility when isolating a CPU to purge any information it may have regarding an orphaned high level cache node. The - OS may use the + OS may use the “ibm,phandle” property to selectively remove caches when a processor is removed. The platform considers any high level cache that is newly referenced (reference count for this partition goes from 0 to 1) to have been previously unreported. - + - R1-R1--4. - For all LRDR options: If a request to + For all LRDR options: If a request to ibm,configure-connector specifies a connector of type MEM, - the returned sub-tree must consist of the specific + the returned sub-tree must consist of the specific ibm,memory-region node containing the properties as would be contained in that node had it been available at boot time. - + - R1-R1--5. - For all LRDR options: If a request to + For all LRDR options: If a request to ibm,configure-connector specifies a connector of type PHB or SLOT, then all of the following must be true: - + The returned values must represent the sub-tree for the specific I/O sub-system represented by the connector, except for entities below @@ -4335,45 +4397,58 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> they been available at boot time, including (if they exist) built-in PCI IOAs. - + - + - R1-R1--6. - For all LRDR options: If a request to + For all LRDR options: If a request to ibm,configure-connector specifies a connector of type SLOT, the returned values must represent the sub-tree for the specific I/O sub-system represented by the SLOT connector, and the - sub-tree must consist of the specific + sub-tree must consist of the specific /pci node and its children all containing the properties as would be contained in those nodes had they been available at boot time, except for the PCI IOA nodes assigned to the OS image that contain the same properties as they would following a PCI hot plug - operation (see + operation (see ). - + - R1-R1--7. For all LRDR options: If a platform implementation powers-up and configures physical DR entities in the sub-tree under a - logical DR connector, then a request to + logical DR connector, then a request to ibm,configure-connector of the logical DR connector - must use the return status of 990x from the + must use the return status of 990x from the ibm,configure-connector call, as necessary, during the DR entity power-up sequence(s) and must control any power-up and sequencing requirements, as would be done by the platform during platform power-up. + + + R1--8. + + For all LRDR options: If a request to + ibm,configure-connector specifies a connector of + type CO- PLATFAC or COPLATFUN, the returned values must represent the + sub-tree for the specific coherent plat- form sub-system represented by + the COPLATFAC or COPLATFUN connector. All properties are updated with + the most recent data from the coherent platform resource. + +
diff --git a/Virtualization/ch_lpar_option.xml b/Virtualization/ch_lpar_option.xml index e61a4dc..ed535ac 100644 --- a/Virtualization/ch_lpar_option.xml +++ b/Virtualization/ch_lpar_option.xml @@ -638,6 +638,26 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Table + + + + / + + + + Prepares for resizing the partition's HPT + + + + + + / + + + + Changes the partition's HPT to a new size + + @@ -1598,21 +1618,81 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - / + / - Prepares for resizing the partition's HPT + Attach a process to a coherent platform function. - / + / - Changes the partition's HPT to a new size + Detach a process to a coherent platform function. + + + + + + / + + + + Control a coherent platform function. + + + + + + / + + + + Collect interrupt information for a coherent platform function. + + + + + + / + + + + Control faults for a coherent platform function. + + + + + + / + + + + Download an application to a coherent platform function. + + + + + + / + + + + Download an application to a coherent platform facility. + + + + + + / + + + + Control a coherent platform facility. @@ -3958,19 +4038,97 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - Reserved + + / + - 0x344-0x354 + 0x344 -   + Normal -   + If one or more Coherent Platform Facilities Options are implemented -   + hcall-ca + + + + + + / + + + + 0x348 + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca + + + + + + / + + + + 0x34C + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca + + + + + + / + + + + 0x350 + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca + + + + + + / + + + + 0x354 + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca @@ -3992,12 +4150,31 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo hcall-clr-hpt + + + + / + + + + 0x35C + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca + + Reserved - 0x35C-0x368 + 0x360   @@ -4009,6 +4186,44 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo   + + + + / + + + + 0x364 + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca + + + + + + / + + + + 0x368 + + + Normal + + + If one or more Coherent Platform Facilities Options are implemented + + + hcall-ca + + @@ -7749,7 +7964,7 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ 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 + memory size, but is unlikely 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 @@ -7758,7 +7973,7 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ 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 + “prepare” 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). @@ -7785,12 +8000,12 @@ hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */ In order to prevent a partition from tying up platform resources - indefinitely with a Pending HPT, the platform is per- mitted to discard a + indefinitely with a Pending HPT, the platform is permitted 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 + for the current memory allocation, rather than the maximum 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 @@ -7950,7 +8165,7 @@ hcall ( const int64 H_RESIZE_HPT_COMMIT, /* Function Code */ 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. + return H_CLOSED. Check that the Pending HPT is fully prepared; if not, @@ -19386,7 +19601,7 @@ hcall ( const uint64 H_GET_EM_PARMS /* Returns in R4 – R9 the Platform Energy - 0b000: Non - floor modes: + 0b000: Non-floor modes: @@ -22018,4 +22233,2995 @@ hcall ( const uint64 H_BULK_READ_HBA, uint64 flags, int64 lpx1, int64 lpx2,
+ +
+ Coherent Platform Facilities + This section documents the hypervisor interface to optional coherent + platform facilities. If the platform supports a coherent platform facility, the + “ibm,hypertas-functions” + property of the + /rtas + node contains the function set specification “hcall-ca” and the following + hcall()s are supported. + + +
+ H_ATTACH_CA_PROCESS + The architectural intent of this hcall is to attach a process element to a + coherent platform function. The process element describes the environment in + which a coherent platform function will operate for a given workload. + + + + Syntax: + + + + + Process Token Format + + + + + + + + Bytes 0-3 + + + + + Bytes 4-7 + + + + + + + + Platform firmware use (opaque to OS) + + + CAIA process element index (128 byte offset into Scheduled Process Area) + + + + +
+ + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” + property, element 0, of the coherent platform function + + + + uint64 process-element-struct: Logical real address of the process + element structure. This memory must remain pinned and unchanged throughout + the duration of the H_ATTACH_CA_PROCESS call. All fields in the structure + have big-endian byte ordering and MSB 0 bit ordering. + + + + uint64 continue-token: Used to continue a process attach if H_Busy is + returned. Set to zero on first call. If H_Busy is returned then call + again but use the value returned in R4 from the previous call as the + value of continue-token. + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + Verify the process-element-struct parameter: + + + Verify that the process-element-struct is 8 byte aligned and + does not cross a 4096 byte boundary, else return H_Parameter. + + + + Verify that the Process Element structure version is supported, + else return H_Parameter. + + + + + + + Verify that if the isPrivilegedProcess bit is set in the process element, + that the coherent platform function is allowed (via + “ibm,privileged-function” + F property), else return H_Authority. + + + + Verify that if the aurpValid bit is set to 1, that the coherent + platform function supports AUR (via + “ibm,supports-aur” + OF property), else return H_Parameter. + + + + Verify that if the csrpValid bit is set to 1, that the coherent platform + function supports CSRP (via + “ibm,supports-csrp” + OF property), else return H_Parameter. + + + + Verify there is adequate space to attach the process for the coherent + platform function else return H_Resource. + + + + Verify that the coherent platform function is in a state that allows + attaching of new processes and if necessary has been downloaded via + H_DOWNLOAD_CA_FUNCTION, else return H_State. + + + + Verify that the sum of the pslVirtualIsn and application + virtual ISN values are greater than or equal to the + “ibm,min-ints-per-process” + property for the coherent-platform-function and less than or equal to the + “ibm,max-ints-per-process” + property for the coherent-platform-function and the attaching of this + process does not violate the + “ibm,max-ints” + property for the coherent-platform-function, else return H_Parameter. + + + + Verify that the pslVirtualIsn is not already in use by another coherent + platform function under the coherent platform facility, if so return + H_Resource. + + + + Validate that the application virtual ISN values are valid and not + in use by another coherent platform function under the coherent platform + facility, and do not collide with the specified pslVirtualIsn, if so + return H_Resource. + + + Application virtual ISN values are calculated by adding the + base virtual ISN value found in the interrupt-ranges property of + the parent coherent platform facility node to the relative offset + (zero-based) of a bit in the bitmap that is set to 1. These + values are programmed into corresponding the CAIA process element + structure. + + + + + + + Verify that all the virtual interrupts can be mapped into the CAIA + process element, else return H_Resource. It may be possible to attempt + to attach the process after detaching existing processes. + + + + Verify that the virtual interrupts provided will fit into the process + element entry, if not return H_Parameter. + + + + Disable the virtual interrupts provided in the process-element-struct. + The partition must use ibm,set-xive (with priority less than 0xFF) to + enable the virtual interrupt source after H_ATTACH_CA_PROCESS completes + successfully. + + + + Select a process element to use for the coherent platform function + and performs the procedure to attach a process as defined by the CAIA. + During this procedure, H_Busy or H_LongBusy will be returned if hcall + time limits are exceeded. + + + + Once the process element is attached as defined by the CAIA, return + H_Success, R4 contains the process token and if + “ibm,process-mmio” + is set to 1, R5 is the MMIO address, R6 is the MMIO length. + + + + Following a reset of the coherent platform facility or coherent platform + function, platform firmware guarantees that the upper 4 byte portion of + the returned process token will be different than it was for any process + token returned since the previous reset. + + +
+ +
+ H_DETACH_CA_PROCESS + The architectural intent of this hcall is to detach a process element + from a coherent platform function. This hcall will remove the workload or p + rocess element that was attached using H_ATTACH_CA_FUNCTION. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” + property of the coherent platform function + + + + uint64 process-token: process identifier token for the attached + process returned in R4 on H_Success return from H_ATTACH_CA_PROCESS call. + + + + uint64 continue-token: Used to continue a process detach if H_Busy + is returned. Set to zero on first call. If H_Busy is returned then + call again but use the value returned in R4 from the previous call + as the value of continue-token. + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return + H_Parameter. + + + + Verify that the process-token is currently an attached process to + the coherent platform function, else return H_Parameter. + + + + Verify that the coherent platform function is in an error state that + allows detaching processes, else return H_State. + + + + If + “ibm,process-mmio” + is set to 1, verify that there are no existing + mappings in the page table for the process + MMIO space, else return H_Resource. + + + + If the process is not completed or suspended, the process is + terminated using the process terminate procedure in the CAIA. During + this process the platform can return H_Busy or H_LongBusy and the OS + is responsible for calling back until a non-busy return code is returned. + + + + Remove the process from the coherent platform function process + element list according to the process remove procedure defined in the + CAIA. During this process the platform can return H_Busy or H_LongBusy + and the OS is responsible for calling back until a non-busy return code + is returned. + + + + Invalidation of the SLB and TLB for the process being detached is + performed. During this process the platform can return H_Busy or + H_LongBusy and the OS is responsible for calling back until a non-busy + return code is returned. + + + + If the hardware encounters an error while detaching the process, + H_Hardware is returned. + + + + H_Success is returned. + + + +
+ +
+ H_CONTROL_CA_FUNCTION + This H_CONTROL_CA_FUNCTION hypervisor call allows the partition to + manipulate or query certain coherent platform function behaviors. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” + property + of the coherent platform facility + + + + uint64 operation: operation to perform to the coherent platform + facility. Valid values are: + + + Reset: operation = 1, perform a reset to the coherent platform + function, this is used when the partition needs to reset the coherent + platform function to a clean state. All attached processes and state + are cleared by firmware after this reset. + + + + Suspend Process: operation = 2, suspend a process from being + executed + + + + Resume Process: operation = 3, resume a process to be executed + + + + Read Error State: operation = 4, read the error state of the + coherent platform function + + + + Get Error Buffer: operation = 5, collect the AFU error buffer + for the coherent platform function. + + + + Get Function Configuration Record: operation = 6, collect + configuration record for the coherent platform function + + + + Get Function Download Status: operation = 7, query to return + download status of a programmable coherent platform function. + + + + Terminate Process: operation = 8, terminate the process + before completion + + + + Collect VPD: operation = 9, collect VPD for the coherent + platform function. + + + + Get Function Error Interrupts: operation = 11, read the + function-wide error data based on an interrupt from + “ibm,function-error-interrupt” + + + + Acknowledge Function Error Interrupts: operation = 12, + acknowledge function-wide error data based on an interrupt from + “ibm,function-error-interrupt” + + + + Get Error Log: operation = 13, retrieve the Platform Log ID + (PLID) of an error log containing error data for the coherent + platform function. This is used after a Temporary Unavailable or + Permanently Unavailable Error State. + + + + + + + uint64 parameter1: parameter 1 for operations, meaning changes based on the operation. + + + + uint64 parameter2: parameter 2 for operations, meaning changes based on the operation. + + + + uint64 parameter3: parameter 3 for operations, meaning changes based on the operation. + + + + uint64 parameter4: parameter 4 for operations, meaning changes based on the operation. + + + + uint64 continue-token: Used to continue an operation if H_Busy is returned. + Set to zero on first call. If H_Busy is returned then call again but use the value + returned in R4 from the previous call as the value of continue-token. + + + + + + + + + + Operation + + + + + Parameters + + + + + + + + Reset + + + None + + + + + Suspect Process + + + + + + Parameter1 = process-token as returned from + H_ATTACH_CA_PROCESS when process was attached. + + + + + + + + Resume Process + + + + + + Parameter1 = process-token as returned from + H_ATTACH_CA_PROCESS when process was attached. + + + + + + + + Read Error State + + + None + + + + + Get Error Buffer + + + + + + Parameter1 = byte offset into error buffer to retrieve, + valid values are between 0 and (ibm,error-buffer-size – 1) + + + Parameter2 = 4K aligned real address of error buffer, + to be filled in + + + Parameter3 = length of error buffer, valid values are + 4K or less + + + + + + + + Get Functional Configuration Record + + + + + + Parameter1 = # of configuration record to retrieve, + valid values are between 0 and (ibm,#config-records – 1) + + + Parameter2 = byte offset into configuration record + to retrieve, valid values are between 0 and + (ibm,config-record-size – 1) + + + Parameter3 = 4K aligned real address of configuration + record buffer, to be filled in + + + Parameter4 = length of configuration buffer, valid values are 4K or less + + + + + + + + Get Function Download Status + + + None + + + + + Terminate Process + + + + + + Parameter1 = process-token as returned from + H_ATTACH_CA_PROCESS when process was attached. + + + + + + + + Collect VPD + + + + + + Parameter1 = # of VPD record to retrieve, valid + values are between 0 and (ibm,#config-records – 1) + + + Parameter2 = 4K naturally aligned real buffer + containing scatter/gather list entries. All fields in the scatter/gather list have big-endian byte ordering. + + + Parameter3 = number of entries in the scatter/gather + list, valid values are between 0 and 256 + + + + + + + + Get Function Error Interrupts + + + None + + + + + Acknowledge Function Error Interrupts + + + + + + Parameter1 = value to write to the function-wide + error interrupt register + + + + + + + + Get Error Log + + + None + + + + + + + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + If operation is Reset: + + + If coherent platform function is in Temporarily Unavailable or + Permanently Unavailable error state or is already performing a reset, + return H_State. + + + + If partition is not allowed to perform a Reset + (“ibm,privileged-function” + property is 0 or not present), return H_Authority. + + + + If coherent platform function has + “ibm,process-mmio” + property set to 1 and partition has any page table mappings existing + for the function, return H_Resource. + + + + If coherent platform function is in Normal error state, set to + Disabled error state. + + + + Terminate and remove all process elements that were attached + via H_ATTACH_CA_PROCESS. If the termination takes longer than is + allowed for an hcall, R4 is set to the continue-token and H_Busy + or H_LongBusy are returned. + + + + If allowed, perform a reset (disable AFU, PSL suspend, PSL + purge, TLB invalidate, SLB invalidate) of the coherent platform + function using CAIA procedures. If the reset takes longer than + is allowed for an hcall, R4 is set to the continue-token and H_Busy + or H_LongBusy are returned. + + + + After the reset, if the coherent-platform-function has the + “ibm,programmable” + property set to 1, a download is required via H_DOWNLOAD_CA_FUNCTION. + The Get Function Download Status operation can be used to query + the download state. + + + + If the coherent-platform-function does not have the + “ibm,programmable” + property or it is set to 0, the AFU is enabled. + + + + If the reset fails while communicating with the hardware, + return H_Hardware. + + + + Reset the error log data for the Get Error Log operation. + + + + Set coherent platform function Error State to Normal and + return H_Success + + + + + + + If operation is Suspend Process: + + + If the coherent platform function is not in a Normal Error State, + return H_State. + + + + If the coherent platform function does not support suspending + processes, return H_Function. + + + + If the process associated with the process token cannot be found, + return H_Parameter. + + + + If the process is not able to be suspended or is already suspended, + return H_State. + + + + The process associated with the process-token is suspended via + the procedure defined in the CAIA. If the suspend takes longer + than is allowed for an hcall, R4 is set to the continue-token and + H_Busy or H_LongBusy are returned. + + + + If the Suspend Process procedure encounters a hardware failure, + return H_Hardware. + + + + Return H_Success. + + + + + + + If operation is Resume Process: + + + If the coherent platform function is not in a Normal Error State, + return H_State. + + + + If the coherent platform function does not support resuming + processes, return H_Function. + + + + If the process associated with the process token cannot be found, + return H_Parameter. + + + + If the process not suspended or resume isn't possible, return + H_State. + + + + The process associated with the process-token is resumed via + the procedure defined in the CAIA. If the resume takes longer than + is allowed for an hcall, R4 is set to the continue-token and H_Busy + or H_LongBusy are returned. + + + + If a hardware error occurs during the Resume Process operation, + return H_Hardware. + + + + Return H_Success. + + + + + + + If operation is Read Error State: + + + Platform firmware checks the error state of the coherent platform + function. If already in an error state, H_Success is returned and + R4 contains the error state. + + + + Platform firmware checks for errors on the coherent platform + function. If errors exist, error recovery is entered and H_Success + is returned and R4 contains the error state. + + + + + + + If operation is Get Error Buffer: + + + If parameter2 does not describe a valid 4K aligned real address, + return H_Parameter. + + + + If parameter3 is greater than 4K, return H_Parameter. + + + + If parameter1 plus parameter3 is greater than or equal to + “ibm,error-buffer-size”, + return H_Parameter. + + + + If the coherent platform function is in a Temporarily Unavailable + or Permanently Unavailable state, return H_State. + + + + Platform firmware collects the error data buffer from the AFU + descriptor associated with the coherent platform function and places + it in the partition buffer described by parameter2 and parameter3. + + + + If the Get Error Buffer operation exceeds the time allowed for + an hcall, R4 is set to the continue-token and H_Busy or H_LongBusy + is returned. + + + + If the error buffer cannot be read from the hardware due to a + hardware problem, return H_Hardware. + + + + Return H_Success. + + + + + + + If operation is Get Function Configuration Record: + + + If parameter1 does not describe a valid configuration record number, + return H_Parameter. + + + + If parameter3 does not describe a valid 4K aligned real address, + return H_Parameter. + + + + If parameter4 is greater than 4K, return H_Parameter. + + + + If parameter2 plus parameter4 is greater than or equal to + “ibm,config-record-size”, + return H_Parameter. + + + + If the coherent platform function is not in a Normal Error State, + return H_State. + + + + If platform firmware cannot retrieve the configuration record + from the coherent platform function, return H_Function. + + + + If platform firmware cannot retrieve the configuration record + due to the coherent platform function not in a downloaded state, r + eturn H_NOT_AVAILABLE. + + + + Platform firmware collects the configuration record from the + coherent platform function and places it in the partition buffer + described by parameter3 and parameter4. The data is stored as a + byte stream; the first byte in the buffer corresponds to byte 0 of + the configuration record. + + + + If the Get Function Configuration Record operation exceeds the + time allowed for an hcall, R4 is set to the continue-token and + H_Busy or H_LongBusy is returned. + + + + If the configuration record cannot be read from the hardware, + due to a hardware problem, return H_Hardware. + + + + Return H_Success. + + + + + + + If operation is Get Function Download Status: + + + If coherent platform function does not support download, + return H_Function. + + + + If the partition does not have the authority to get download status + (“ibm,privilegedfunction” + property is 0 or not present), return H_Authority. + + + + If the coherent platform function is not in a Normal or + Disabled Error State, return H_State. + + + + Platform firmware returns the download status in R4, where + 0 = no-download-found and 1 = download-found. + + + + Return H_Success. + + + + + + + If operation is Terminate Process: + + + If the coherent platform function is not in a Normal Error State, + return H_State. + + + + If the coherent platform function does not support terminating + processes, return H_Function. + + + + If the process associated with the process token cannot be found, + return H_Parameter. + + + + If the process has already completed, return H_State. + + + + The process associated with the process-token is terminated + via the procedure defined in the CAIA. If the attempt to terminate + the process takes longer than is allowed for an hcall, R4 is set + to the continue-token and H_Busy or H_LongBusy are returned. + + + + If a hardware error occurs during the Terminate Process operation, + return H_Hardware. + + + + Return H_Success. + + + + + + + If the operation is Collect VPD: + + + If parameter1 does not describe a valid VPD record number, + return H_Parameter. + + + + If parameter2 does not describe a valid 4K aligned real address, + return H_Parameter. + + + + If parameter3 is greater than 256, return H_Parameter. + + + + If a scatter/gather list entry specifies an invalid address, or + specifies a buffer that crosses a page boundary, return H_SG_LIST. + + + + If the coherent platform function is not in a Normal Error State, + return H_State. + + + + If platform firmware cannot retrieve the VPD from the coherent + platform function, return H_Function. + + + + If platform firmware cannot retrieve the VPD due to the coherent + platform function not in a downloaded state, return H_NOT_AVAILABLE. + + + + Platform firmware collects the VPD from the coherent platform + function and places it in the partition buffer described by parameter2 + and parameter3. The data will be truncated as necessary to fit in the + provided buffer. The data is stored as a bytestream; the first byte + in the buffer corresponds to byte 0 of the VPD. + + + + If the Collect VPD operation exceeds the time allowed for an hcall, + R4 is set to the continue-token and H_Busy or H_LongBusy is returned. + + + + If a hardware error occurs during the Collect VPD operation, r + eturn H_Hardware. + + + + Return H_Success, and R4 is set to the length of the available + VPD, which may be different than the amount of data actually stored + in the partition buffer. It may also be different than the value + reported in the + “ibm,vpd-size” + property, though it will not be greater than that. A length of + 0 means no VPD has been provided for the coherent platform function. + + + + + + + If the operation is Get Function Error Interrupts: + + + If the coherent platform function is not in a Normal Error or + Disabled State, return H_State. + + + + If the coherent platform function does not support Get Function + Error Interrupts, return H_Function. + + + + If the Function Error Interrupts cannot be retrieved from the + hardware, return H_Hardware. + + + + Platform firmware returns the value of Function Error Interrupts + read from hardware in R4. + + + + Return H_Success. + + + + + + + If the operation is Acknowledge Function Error Interrupts: + + + If the coherent platform function is not in a Normal or Disabled + Error State, return H_State. + + + + If the coherent platform function does not support Acknowledge + Function Error Interrupts, return H_Function. + + + + Acknowledge Function Error Interrupts using the value in + parameter1. + + + + If the Acknowledge Function Error Interrupts cannot be sent + to the hardware, return H_Hardware. + + + + Return H_Success. + + + + + + + If operation is Get Error Log: + + + If the coherent platform function is not in Disabled or + Permanently Unavailable Error State, return H_State. + + + + If applicable, platform firmware writes the Platform Log ID + (PLID) in R4 for the error log that is associated with the cause + of the Temporarily Unavailable or Permanently Unavailable Error State. + This data is used to correlate errors between the platform owned + resource and the coherent platform function. If there is no + associated error log to reference, platform firmware writes zero to R4. + + + + Return H_Success. + + + + + + + If operation is unknown, return H_Not_Found. + + + +
+ +
+ H_COLLECT_CA_INT_INFO + The architectural intent of this hcall is to collect interrupt info about + a coherent platform function after an interrupt occurred. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” property + of the coherent platform facility + + + + uint64 process-token: process identifier token for the attached + process returned in R4 on H_Success return from H_ATTACH_CA_PROCESS call. + + + + + + Return Values: + + + R4 contains the PSL_DSISR_An register value defined in the CAIA on + H_Success. + + + + R5 contains the PSL_DAR_An register value defined in the CAIA on + H_Success. + + + + R6 contains the PSL_DSR_An register value defined in the CAIA on + H_Success. + + + + R7 contains the PSL_PID_An in the upper 32 bits and PSL_TID_An + register in the lower 32 bits. + + + + R8 contains the AFU_ERR_An register value defined in the CAIA on + H_Success. + + + + R9 contains the PSL_ErrStat_An register value defined in the + CAIA on H_Success. + + + + R10 contains a handle for the process element that incurred + the fault on H_Success. + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + Verify that the process-token parameter is valid else return + H_Parameter. + + + + Verify that the coherent platform function is in the proper state + to read interrupt information else return H_State. + + + + Platform firmware reads the values of PSL_DSISR_An, PSL_DAR_An, + PSL_DSR_An, PSL_DSR_An, PSL_PID_An, PSL_TID_An, AFU_ERR_An and + PSL_ErrStat_An as defined by the CAIA and populates the return registers. + AFU_ERR_An value is only valid if PSL_DSISR[AE] is 1 or PSL_SERR_An[AE] + is 1. PSL_ErrStat_An value is only valid if PSL_DSISR[PE] is 1. If any + of the reads fail from the hardware H_Hardware is returned and none of + the return registers should be considered valid. + + + + H_Success is returned. + + + +
+ +
+ H_CONTROL_CA_FAULTS + The architectural intent of this hcall is to control the operation of a + coherent platform function after a fault occurs. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” property + of the coherent platform facility + + + + uint64 operation: operation to perform to the coherent platform + facility. Valid values are: + + + Respond to page fault - PSL: operation = 1. + + + + Respond to page fault - AFU: operation = 2. + + + + + + + uint64 parameter1: parameter 1 for operations, meaning changes based on the operation. + + + + uint64 parameter2: parameter 2 for operations, meaning changes based on the operation. + + + + uint64 parameter3: parameter 3 for operations, meaning changes based on the operation. + + + + uint64 parameter4: parameter 4 for operations, meaning changes based on the operation. + + + + + + + + + + + + Operation + + + + + Parameters + + + + + + + + Respond to page fault - PSL + + + + + + Parameter1 = process-token as returned from H_ATTACH_CA_PROCESS + + + Parameter2 = control-mask + + + bits 0-59: reserved + + + bit 60: acknowledge non-translation fault interrupt + + + bit 61: continue execution, current translation + fault is not resolved and must be retried at a later time + + + bit 62: restart function and indicate address error + + + bit 63: restart the transaction that caused the + translation fault + + + + + + Parameter3 = reset-mask + + + bit 0-62: reserved + + + bit 63: reset fault bits for a PSL level process + error (PSL_DSISR_An[PE] is set) + + + + + + + + + + + Respond to page fault - AFU + + + + + + Parameter1 = process-token + + + Parameter2 = process element handle returned from + H_COLLECT_CA_INT_INFO. + + + Parameter3 = effective address + + + Parameter4 = resolution, valid values are: + + + 0x0 -- Page Fault Resolved + + + 0x1 -- Addressing Error + + + 0x2 -- Protection Fault on a Read operation + + + 0x3 -- Protection Fault on a Write operation + + + + + + + + + + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + If operation is Respond to page fault - PSL: + + + Verify that the process-token parameter is valid else return + H_Parameter. + + + + Verify that the coherent platform function is in a valid state + else return H_State. + + + + Using the control-mask set the corresponding bits in + PSL_TFC_An as defined by CAIA. Only bits that are set are written. + If no bits are set, no changes are performed. If the setting of + the bits in the hardware encounters an error, return H_Hardware. + + + + If bit 63 of the reset-mask is set, clear the PSL_ErrStat_An + bits by reading the register and writing back the value read. If + this operation encounters an error with the hardware, return + H_Hardware. + + + + Perform a read from PSL_TFC_An and place corresponding values + in R4. If the read fails, return H_Hardware. + + + + Return H_Success with the following in R4: + + + bits 0-60: reserved + + + + bit 61: function waiting to continue + + + + bit 62: address error pending + + + + bit 63: command reissue pending + + + + + + + + + + If operation is Respond to page fault - PSL: + + + Verify that the process-token parameter is valid else return + H_Parameter. + + + + Verify that the resolution parameter is valid else return + H_Parameter. + + + + Verify that the coherent platform function is in a valid state + else return H_State. + + + + Verify that the coherent platform function supports paged + resolution response (via + “ibm,supports-prr” + OF property), else return H_Function. + + + + Write the effective address and resolution to the corresponding + fields in the PRR registers of the AFU. If this operation encounters + an error with the hardware, return H_Hardware. + + + + Return H_Success. + + + + + + If operation is unknown, return H_Not_Found. + + + +
+ +
+ H_DOWNLOAD_CA_FUNCTION + The architectural intent of this hcall is to provide platform support for + downloading an application image to the coherent platform function. The + partition provides download data to the platform via an image scatter/gather + list. The scatter/gather list can architecturally describe up to 1 megabyte + of data (256 entries of 4096 bytes each). The OS must subdivide the application + image into chunks that are each 1 megabyte or less in size, and call H + _DOWNLOAD_CA_FUNCTION for each of those chunks. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” property + of the coherent platform facility + + + + uint64 scatter-gather-list-address: 4K naturally aligned real buffer + containing scatter/gather list entries. All fields in + the scatter/gather list and all fields in the image header have + big-endian byte ordering. + + + + uint64 num-scatter-gather-list-entries: number of entries + in the scatter/gather list + + + + uint64 continue-token: Used to continue an operation if H_Busy or + H_CONTINUE is returned. Set to zero on first call. If H_Busy or + H_CONTINUE is returned then call again but use the value returned in + R4 from the previous call as the value of continue-token. + + + + Image Scatter/Gather List Entry Format + + + + + + + 8 byte logical real address of buffer + + + 8 byte buffer length in bytes (max length is 4096 bytes) + + + + +
+ + + + Image Scatter/Gather List Format + + + + + + + Logical real address of buffer 0 + + + Buffer 0 length in bytes) + + + + + Logical real address of buffer 1 + + + Buffer 1 length in bytes) + + + + + ... + + + ... + + + + + Logical real address of buffer N-1 + + + Buffer N-1 length in bytes) + + + + + Logical real address of buffer N + + + Buffer N length in bytes) + + + + +
+ + + + Application Image Header, Version 1 + + + + + + + + + + Name + + + + + Offset + + + + + Length + + + + + Description + + + + + + + + Version + + + 0 + + + 2 + + + Version of the AFU image header, value = 1 + + + + + Function Number + + + 2 + + + 2 + + + Physical function number that the application uses + + + + + Application ID + + + 4 + + + 2 + + + Application identifier + + + + + Reserved + + + 6 + + + 2 + + + Set to zero. + + + + + Vendor ID + + + 8 + + + 2 + + + PCI Vendor ID of the adapter owning the coherent + platform function + + + + + Device ID + + + 10 + + + 2 + + + PCI Device ID of the adapter owning the coherent + platform function + + + + + Subsystem Vendor ID + + + 12 + + + 2 + + + PCI Subsystem Vendor ID of the adapter owning the coherent + platform function + + + + + Subsystem ID + + + 14 + + + 2 + + + PCI Subsystem ID of the adapter owning the coherent + platform function + + + + + Image Offset + + + 16 + + + 8 + + + Offset to the application image bitstream + + + + + Image Length + + + 24 + + + 8 + + + Length of the application image bitstream + + + + + Verification Type + + + 32 + + + 2 + + + Type of verification required for image: + + + 1 = Bounds Check + + + All other values reserved + + + + + + + + Reserved + + + 34 + + + 6 + + + Set to zero + + + + + CAIA Version + + + 40 + + + 2 + + + Minimum CAIA Version required by this application image + + + + + PSL Revision + + + 42 + + + 2 + + + Minimum PSL Revision required by this application image + + + + + Reserved + + + 44 + + + 84 + + + Set to zero + + + + +   + + + + + Image Bitstream + + + X + + + Y + + + Application image bitstream, where X = Image + Offset and Y = Image Length + + + + +
+ + + + + + + + Return Values: + + + R4 on H_Busy or H_LongBusy or H_CONTINUE contains the continue-token + to be used on the next call + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + If the coherent-platform-facility cannot be downloaded at this + time due to a resource constraint, H_Resource is returned. + + + + If the coherent platform facility does not support download, + return H_Function. + + + + If the coherent platform function is already downloaded, or if a + download is in progress, return H_State. + + + + If the partition does not have the authority to perform download + (“ibm,privileged-function” + property is 0 or not present), return H_Authority. + + + + If the coherent platform facility is in a Temporary Unavailable + Error State or has attached processes, return H_State. + + + + If the scatter-gather-list-address does not describe a 4K byte + naturally aligned buffer, return H_Parameter. + + + + If the Application Image Header version is not supported by platform + firmware, return H_BAD_DATA. + + + + If necessary, platform firmware disables the coherent platform facility + from operation. + + + + For each entry in the scatter/gather list described by + scatter-gather-list-address: + + + Platform firmware validates address and length in the scatter/gather + list entry. The buffer described should not cross a 4K page boundary. + If invalid, returns H_SG_LIST. + + + + Platform firmware copies data from the scatter/gather list entry + to the platform firmware buffer. + + + + Platform firmware verifies the image bitstream data chunk in the + platform buffer. If platform firmware determines the image bitstream + data chunk is not valid, return H_BAD_DATA. During this operation, + H_Busy or H_LongBusy can be returned due to hcall maximum time + limits, the partition should call back, until a non-busy return + code is returned. + + + + Platform firmware performs the download for the + coherent platform facility, using the image bitstream data chunk. + During this operation, H_Busy or H_LongBusy can be returned due to + hcall maximum time limits, the partition should call again, until a + non-busy return code is returned. + + + + If the coherent platform facility does not accept the download + of the image bitstream data chunk or an error occurs while + communicating with the hardware, H_Hardware is returned. + + + + If hcall time limit is exceeded, but more data is left to + copy in the current scatter/gather list, H_Busy or H_LongBusy is + returned. The partition should call back with the current + scatter/gather list. + + + + + + + Once every entry in the current scatter/gather list is copied, + platform firmware returns H_CONTINUE. The partition then calls back + with a new scatter/gather list for the next chunk of image data and the + previous steps are repeated for each new list. This is repeated as long + as H_CONTINUE is returned. + + + + The CAIA AFU descriptor is read for the downloaded AFU, if any + fields in the AFU descriptor are not compatible with the PSL, + H_UNSUPPORTED is returned. + + + + If the Download operation completes successfully, if necessary, + platform firmware re-enables coherent platform function for operation. + + + + H_Success is returned. + + + + + Any error in the above steps will cause the download to be aborted. + The partition must retry H_DOWNLOAD_CA_FUNCTION, starting with the + Application Image header in order to complete the download. + + + After H_DOWNLOAD_CA_FUNCTION is performed, the partition should call + ibm,update-nodes and ibm,update-properties + to receive the current configuration for the coherent platform facility. + + + When H_DOWNLOAD_CA_FUNCTION is first called, some AFU or adapter resources + may be reserved for use during the download sequence, which may span + multiple H_DOWNLOAD_CA_FUNCTION calls, until the image download is + complete as indicated by a return of H_SUCCESS. When H_CONTINUE is returned, + indicating that more data is needed for the complete AFU image, the OS must call + H_DOWNLOAD_CA_FUNCTION again within 1 milliseconds, or the download sequence will + be abandoned and the OS may need to reset the AFU and restart the + download sequence from the beginning. + + +
+ +
+ H_DOWNLOAD_CA_FACILITY + + The architectural intent of this hcall is to provide platform support for + downloading a base adapter image to the coherent platform facility, and for + validating the entire image after the download. The partition provides download + data to the platform via an image scatter/gather list. The scatter/gather list + can architecturally describe up to 1 megabyte of data (256 entries of 4096 + bytes each). The OS must subdivide the base adapter image into chunks that are + each 1 megabyte or less in size, and call H_DOWNLOAD_CA_FACILITY for each of + those chunks. + Base adapter image download requires two separate operations. The first is + the download operation, which processes the entire image, possibly returning + H_CONTINUE a number of times, and completing when H_Success is returned. The + second is the validate operation, which again processes the entire image with + a number of H_CONTINUE returns until it completes with H_Success. The base + adapter image is not usable until both operations have completed successfully. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” property + of the coherent platform facility + + + + uint64 operation: operation to perform to the coherent platform + facility. Valid values are: + + + Download: operation = 1, the base image in the coherent platform + facility is first erased, and then programmed using the image supplied + in the scatter/gather list. + + + + Validate: operation = 2, the base image in the coherent platform + facility is compared with the image supplied in the scatter/gather list. + + + + + + + uint64 scatter-gather-list-address: 4K naturally aligned real buffer + containing scatter/gather list entries. The format of the scatter/gather + list is the same as for the H_DOWNLOAD_CA_FUNCTION hcall. All fields in + the scatter/gather list and all fields in the image header have + big-endian byte ordering. + + + + uint64 num-scatter-gather-list-entries: number of block list entries + in the scatter/gather list + + + + uint64 continue-token: Used to continue an operation if H_Busy or + H_CONTINUE is returned. Set to zero on first call. If H_Busy or + H_CONTINUE is returned then call again but use the value returned in + R4 from the previous call as the value of continue-token. + + + Base Adapter Image Header, Version 1 + + + + + + + + + + Name + + + + + Offset + + + + + Length + + + + + Description + + + + + + + + Version + + + 0 + + + 2 + + + Version of the base adapter image header, value = 1 + + + + + Reserved + + + 2 + + + 6 + + + Set to zero. + + + + + Vendor ID + + + 8 + + + 2 + + + PCI Vendor ID of the coherent platform facility + + + + + Device ID + + + 10 + + + 2 + + + PCI Device ID of the coherent platform facility + + + + + Subsystem Vendor ID + + + 12 + + + 2 + + + PCI Subsystem Vendor ID of the coherent platform facility + + + + + Subsystem ID + + + 14 + + + 2 + + + PCI Subsystem ID of the coherent platform facility + + + + + Image Offset + + + 16 + + + 8 + + + Offset to the base adapter image bitstream + + + + + Image Length + + + 24 + + + 8 + + + Length of the base adapter image bitstream + + + + + Reserved + + + 32 + + + 96 + + + Set to zero + + + + +   + + + + + Image Bitstream + + + X + + + Y + + + Base adapter image bitstream, where X = Image + Offset and Y = Image Length + + + + +
+ + + + + + + Return Values: + + + R4 on H_Busy or H_LongBusy or H_CONTINUE contains the continue-token + to be used on the next call + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, + else return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + If the coherent-platform-facility cannot be downloaded at this + time due to a resource constraint, H_Resource is returned. + + + + If the coherent platform facility does not support download, + return H_Function. + + + + If a download is in progress for the coherent + platform facility, return H_State. + + + + If the partition does not have the authority to perform download + (“ibm,privileged-function” + property is 0 or not present), return H_Authority. + + + + If the coherent platform facility is in a Temporary Unavailable E + rror State, return H_State. + + + + If the scatter-gather-list-address does not describe a 4K byte + naturally aligned buffer, return H_Parameter. + + + + If the Base Adapter Image Header version is not supported by platform + firmware, return H_BAD_DATA. + + + + If necessary, platform firmware disables the coherent platform facility + from operation. + + + + For each entry in the scatter/gather list described by + scatter-gather-list-address: + + + Platform firmware validates address and length in the scatter/gather + list entry. The buffer described should not cross a 4K page boundary. + If invalid, returns H_SG_LIST. + + + + Platform firmware copies data from the scatter/gather list entry + to the platform firmware buffer. + + + + Platform firmware verifies the image bitstream data chunk in the + platform buffer. If platform firmware determines the image bitstream + data chunk is not valid, return H_BAD_DATA. During this operation, + H_Busy or H_LongBusy can be returned due to hcall maximum time + limits, the partition should call back, until a non-busy return + code is returned. + + + + Platform firmware performs the download or validate operation for the + coherent platform facility, using the image bitstream data chunk. + During this operation, H_Busy or H_LongBusy can be returned due to + hcall maximum time limits, the partition should call again, until a + non-busy return code is returned. + + + + If the coherent platform facility does not accept the download + of the image bitstream data chunk or an error occurs while + communicating with the hardware, H_Hardware is returned. + + + + If hcall time limit is exceeded, but more data is left to + copy in the current scatter/gather list, H_Busy or H_LongBusy is + returned. The partition should call back with the current + scatter/gather list. + + + + + + + Once every entry in the current scatter/gather list is copied, + platform firmware returns H_CONTINUE. The partition then calls back + with a new scatter/gather list for the next chunk of image data and the + previous steps are repeated for each new list. This is repeated as long + as H_CONTINUE is returned. + + + + If the validate operation completes successfully, platform + firmware re-enables coherent platform facility for operation if necessary. + + + H_Success is returned. + + + + + Any error in the above steps will cause the download to be aborted. + To complete the download, the partition must retry both H_DOWNLOAD_CA_FACILITY + operations, including the Base Adapter Image header for each operation. + + + After H_DOWNLOAD_CA_FACILITY is performed, the partition should call + ibm,update-nodes and ibm,update-properties + to receive the current configuration for the functions under this + coherent platform facility. + + + When H_DOWNLOAD_CA_FACILITY is first called, some adapter resources + may be reserved for use during the download sequence, which may span + multiple H_DOWNLOAD_CA_FACILITY calls, until the image download is + complete as indicated by a return of H_SUCCESS. When H_CONTINUE is returned, + indicating that more data is needed for the complete image, the OS must call + H_DOWNLOAD_CA_FACILITY again within 3 seconds, or the download sequence may + be abandoned and the OS may need to reset the facility and restart the + download sequence from the beginning. + + +
+ +
+ H_CONTROL_CA_FACILITY + This H_CONTROL_CA_FACILITY hypervisor call allows the partition to manipulate + or query certain coherent platform facility behaviors. + + + Syntax: + + + + + Parameters: + + + uint64 unit-address: Unit Address per the device tree + “reg” property + of the coherent platform facility + + + + uint64 operation: operation to perform to the coherent platform + facility. Valid values are: + + + Reset: operation = 1, initiate a reset to the coherent platform + facility, this is used when the partition needs to reset the + coherent platform facility and all of its child coherent platform + functions to a clean state. All attached processes and state are + cleared by firmware after this reset. If a new base adapter image + has been downloaded, that image will be activated. + + + + Collect VPD: operation = 2, collect VPD for the coherent + platform facility. + + + + + + + uint64 parameter1: parameter 1 for operations, meaning changes based on the operation. + + + + uint64 parameter2: parameter 2 for operations, meaning changes based on the operation. + + + + uint64 parameter3: parameter 3 for operations, meaning changes based on the operation. + + + + uint64 parameter4: parameter 4 for operations, meaning changes based on the operation. + + + + uint64 continue-token: Used to continue an operation if H_Busy is returned. + Set to zero on first call. If H_Busy is returned then call again but use the value + returned in R4 from the previous call as the value of continue-token. + + + + + + + + + + Operation + + + + + Parameters + + + + + + + + Reset + + + None + + + + + Collect VPD + + + + + + Parameter1 = 4K naturally aligned real buffer containing + scatter/gather list entries. All fields in the scatter/gather + list have big-endian byte ordering. + + + Parameter2 = number of entries in the scatter/gather + list, valid values are between 0 and 256 + + + + + + + + + + + + + + + Semantics: + + + Verify that coherent platform facilities are licensed to be used, else + return H_Authority. + + + + Verify that the unit-address parameter is valid else return H_Parameter. + + + + If operation is Reset: + + + If coherent platform facility is in Temporarily Unavailable error + state or is already performing a reset, return H_State. + + + + If partition is not allowed to perform a Reset + (“ibm,privileged-facility” + property is 0 or not present), return H_Authority. + + + + Set Temporarily Unavailable error state for the coherent + platform facility and all child coherent platform functions. + + + + Initiate reset of the coherent platform facility. + + + + If the Reset operation exceeds the time allowed for an hcall, + R4 is set to the continue-token and H_Busy or H_LongBusy is returned. + + + + Return H_Success + + + + + + + If operation is Collect VPD: + + + If parameter1 does not describe a valid 4K aligned real address, return H_Parameter. + + + + If parameter2 is greater than 256, return H_Parameter. + + + + If a scatter/gather list entry specifies an invalid address, + or specifies a buffer that crosses a page boundary, return H_SG_LIST. + + + + If the coherent platform facility is not in a Normal Error State, + return H_State. + + + + If platform firmware cannot retrieve the VPD from the coherent + platform facility, return H_Function. + + + + Platform firmware collects the VPD from the coherent platform + facility and places it in the partition buffer described by + parameter1 and parameter2. The data will be truncated as necessary + to fit in the provided buffer. The data is stored as a bytestream; + the first byte in the buffer corresponds to byte 0 of the VPD. + + + + If the Collect VPD operation exceeds the time allowed for an hcall, + R4 is set to the continue-token and H_Busy or H_LongBusy is returned. + + + + If a hardware error occurs during the Collect VPD operation, + return H_Hardware. + + + + Return H_Success, and R4 is set to the length of the available VPD, + which may be different than the amount of data actually stored in the + partition buffer. It may also be different than the value reported in the + “ibm,vpd-size” + property, though it will not be greater than that. A length of 0 + means no VPD has been provided for the coherent platform facility. + + + + + + + If operation is unknown, return H_Not_Found. + + + +
+
diff --git a/Virtualization/ch_virtual_io.xml b/Virtualization/ch_virtual_io.xml index b1127c0..7ecc34d 100644 --- a/Virtualization/ch_virtual_io.xml +++ b/Virtualization/ch_virtual_io.xml @@ -4160,7 +4160,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ the Hypervisor should wait after enqueueing the “Prepare for Suspend” transport event on the server's command queue until receiving the H_VIOCTL READY_FOR_SUSPEND subfunction from the server. The - time- out value should take into account the maximum amount of + timeout value should take into account the maximum amount of time to queisce I/O operations prior to migration of the client partition. @@ -4198,10 +4198,10 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ event on a VSCSI or VFC server adapter for which this function is called. If enabled via the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction, the server should call this H_VIOCTL READY_FOR_SUSPEND subfunction after receiving the - “Prepare For Sus- pend” transport event and quiescing I/O operations to the + “Prepare For Suspend” transport event and quiescing I/O operations to the backing store. If the server is unable to call this subfunction within the timeout specified in the H_VIOCTL ENABLE_PREPARE_FOR_SUSPEND subfunction, - the migration op- eration on the client partition will be aborted. + the migration operation on the client partition will be aborted. Validate that the unit-address corresponds to a VSCSI or VFC