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 TopologyVPD 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-C2Blade 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 keywordFormat:
- 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
nameThe 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".
+
+
@@ -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> PropertyThis 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> PropertyThis 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> PropertyThis 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> PropertyThis 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> PropertyThis 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> PropertyThis 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
.
-
+
- 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 OptionThis 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 RequirementsA 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 SlotsAn 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