From ea32391eb31c1b8edafcc761201b3a130f8cb912 Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Fri, 13 Oct 2017 08:47:12 -0500 Subject: [PATCH] Draft update - Complete Platform document cleanup - Ensure build of all docs in POM - General cross-doc cleanup Signed-off-by: Jeff Scheel --- DeviceTree/bk_main.xml | 101 +- DeviceTree/ch_devtree_pa.xml | 33 +- DeviceTree/ch_devtree_system.xml | 864 +- Error Handling/bk_main.xml | 101 +- ...sec_rtas_error_reporting_return_format.xml | 230 +- Error Handling/sec_rtas_hot_plug.xml | 18 +- Platform/bk_main.xml | 101 +- Platform/ch_product_topology.xml | 273 +- Platform/ch_system_reqs.xml | 60 +- README.md | 2 +- RTAS/bk_main.xml | 101 +- RTAS/ch_firmware_dump.xml | 2187 ++++- RTAS/ch_rtas_call_defn.xml | 576 +- RTAS/ch_rtas_environment.xml | 4 +- RTAS/sec_rtas_get_indices.xml | 207 +- Virtualization/bk_main.xml | 101 +- Virtualization/ch_dynamic_reconfig.xml | 171 +- Virtualization/ch_lpar_option.xml | 7723 ++++++++++++----- Virtualization/ch_virtual_io.xml | 710 +- 19 files changed, 10646 insertions(+), 2917 deletions(-) diff --git a/DeviceTree/bk_main.xml b/DeviceTree/bk_main.xml index 8238c3f..2573b57 100644 --- a/DeviceTree/bk_main.xml +++ b/DeviceTree/bk_main.xml @@ -42,7 +42,7 @@ OpenPOWER Foundation - Revision 2.0_pre1 + Revision 2.0_pre2 OpenPOWER @@ -71,6 +71,105 @@ + + 2017-10-11 + + + + Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows: + + + ISA 2.07 privileged doorbell extensions (9/16/2012) + + + POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012) + + + Enable Multiple Redirected RDMA mappings per page (3/5/2013) + + + Add Block Invalidate Option (3/5/2013) + + + Implementation Dependent Optimizations (3/13/2013) + + + System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013) + + + New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013) + + + Remove Client-Architecture-Support bit for UUID option (4/16/2013) + + + AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013) + + + Add VNIC Server (5/24/2014) + + + VPA changes for P8 (EBB) (5/24/2013) + + + Add an hcall to clean up the entire MMU hashtable (11/20/2013) + + + Add LPCR[ILE] support to H_SET_MODE (5/31/2013) + + + New Root Node Properties (1/12/2016) + + + Extended Firmware Assisted Dump for P8 Registers (1/24/2014) + + + Sufficient H_COP_OP output buffer (6/21/2014) + + + Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014) + + + Extend H_GET_MPP_X reporting coalesced pages (8/24/2014) + + + Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015) + + + Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015) + + + Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015) + + + Additional System Parameter to read LPAR Name string (10/7/2015) + + + Redesign of properties for DRC information and dynamic memory (7/23/2015) + + + Add additional logical loction code sections (3/4/2016) + + + Add ibm,vnic-client-mac to support vNIC failover (2/29/2016) + + + hcall for registering the process table (3/21/2016) + + + New device tree property for UUID (3/21/2016) + + + Changes for Hotplug RTAS Events (10/24/2016) + + + Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016) + + + + + + 2016-05-04 diff --git a/DeviceTree/ch_devtree_pa.xml b/DeviceTree/ch_devtree_pa.xml index 1cfe59c..51c5a5c 100644 --- a/DeviceTree/ch_devtree_pa.xml +++ b/DeviceTree/ch_devtree_pa.xml @@ -683,7 +683,7 @@ Standard property name. The value of this property for CPU nodes shall be - “cpu”. + “cpu”. @@ -710,23 +710,21 @@ - “okay” - for a good processor. + “okay” for a good processor. - “fail” - for a processor that fails during power-on testing. + “fail” for a processor that fails during power-on testing. - “fail-offline” + “fail-offline” for a processor that has been automatically deconfigured because of previous failures. - “disabled” + “disabled” for a processor that has been manually deconfigured. @@ -1189,7 +1187,7 @@ “ibm,processor-page-sizes” - property name: Relates the number and sizes of the virtual memory + property name: Relates the number and sizes of the virtual memory page sizes supported by the processor describe by this node. prop-encoded-array: One to N cells in ascending value order, each encoded as with @@ -1201,6 +1199,19 @@ + + “ibm,processor-radix-AP-encodings” + + property name: Relates the AP (Actual Page size) encodings + for the supported page sizes used by the TLB management instructions when the processor + is in Radix address translation mode. + prop-encoded-array: One to N cells in ascending order of + Radix mode supported page size, each encoded as with + encode-int. The top 3 bits of the low order byte + contain the tlbie AP field associated with the corresponding Radix mode supported page size. + + + “ibm,processor-segment-sizes” @@ -1996,12 +2007,12 @@ 0 - 2.07 Vector.XOR Support + 2.07 Vector.CRYPTO Support - The value of 1 indicates that the vector.xor category as + The value of 1 indicates that the vector.crypto category as described by version 2.07 of POWER ISA is supported; else the - 2.07 version vector.xor category is not supported. + 2.07 version vector.crypto category is not supported. diff --git a/DeviceTree/ch_devtree_system.xml b/DeviceTree/ch_devtree_system.xml index 206cf68..15783d5 100644 --- a/DeviceTree/ch_devtree_system.xml +++ b/DeviceTree/ch_devtree_system.xml @@ -285,9 +285,9 @@ device:bootinfo - bootinfo is the value of the “ - bootinfo ” property in a /rom child - node + bootinfo is the value of the + “bootinfo” property in a + /rom child node @@ -748,10 +748,79 @@
Properties for Dynamic Reconfiguration - The following standard properties are define for all dynamically - reconfigurable platform nodes. + The following property, when present, replaces the following four properties: + “ibm,drc-indexes”, + “ibm,drc-names”, + “ibm,drc-types” and + “ibm,drc-power-domains”. + This property is defined for all dynamically reconfigurable platform nodes. + + “ibm,drc-info” + + property name that defines all required DR information in a new format + prop-encoded-array: The first element of the array is the number of drc-info entries, + encoded with + encode-int + The drc-info entry consists of the following elements: + + + The drc-type encoded with + encode-string. + Examples include “MEM” “PHB” and “CPU” + + + + The drc-name-prefix encoded with + encode-string. + Examples include “LMB” “PHB “ “CPU “ and “U8233.E8B.1000C9P-V1-C” + + + + The drc-index-start encoded with + encode-int. + The first drc-index of the first entity in the sequence of + entities described by this ibm,drc-info entry. + + + + The drc-name-suffix-start encoded with + encode-int. + The integer value that is to be converted to asci and appended to the + drc-name-prefix to create the complete + drc-name of the first entity in the sequence of entities + described by this ibm,drc-info entry. + + + + The number-sequential-elements encoded with + encode-int. + The number of sequential entities described by this + ibm,drc-info entry. + + + + The sequential-increment encoded with + encode-int. + The number by which to increment the drc-index and the name-suffix + for each sequential entity. + + + + The drc-power-domain encoded with + encode-int. + + + + + + + The following properties have been replaced by the + “ibm,drc-info” but are documented + here for legacy purposes: + + “ibm,drc-indexes” @@ -1809,7 +1878,7 @@ property name indicating that the platform supports the potential migration of this partition. - prop-encoded-array: NULL + prop-encoded-array: <NULL> @@ -1939,6 +2008,178 @@ + + + “ibm,guid-partition-table” + + + property name indicates that the partition supports disks + with the GUID Partition Table. + + prop-encoded-array: <NULL> + + + + + “ibm,linux-le-capable” + + + property name indicates that the partition is capable of + supporting boot of Little Endian Linux. + + prop-encoded-array: <NULL> + + + + + “ibm,partition-uuid” + + + property name specifies a universally unique identifier for this partition. + + prop-encoded-array: A string of data as described below, encoded as with + encode-string + The Universally Unique IDentifier (UUID) option provides each partition with a + Universally Unique Identifier that is persisted by the platform across partition + reboots, reconfigurations, OS reinstalls, partition migration, hibernation etc. + The UUID is a 16 byte string of format fields and random bits as defined in + . + The random bits are generated in an implementation-dependent manner to + achieve a projected probability of collision of not greater than one in 260. + + + UUID Format + + + + + + + + + + Field + + + + + Byte:Bit + + + + + Size (Bits) + + + + + Values + + + + + + + + Version + + + 0:0 + + + 1 + + + 0: Initial Version + 1: Reserved + + + + + Random Bits + + + 0:1 thru 5:7 + + + 47 + + + Random Bits + + + + + Generation Method + + + 6:0-3 + + + 4 + + + 0b0000 Never Used + 0b0100 Random Generated + All other values are reserved + + + + + Random Bits + + + 6:4 - 7:7 + + + 12 + + + Random Bits + + + + + Variant + + + 8:0-1 + + + 2 + + + 0b10 DCE Variant UUID + All other values are reserved + + + + + Random Bits + + + 8:2 - 15:7 + + + 62 + + + Random Bits + + + + +
+ + + For the GET_PARTNER_UUID subfunction (See ), the data is + represented as 16 bytes as described in . + For the ibm,partition-uuid property, the data is represented as a string of + hexadecimal characters, with hyphens added for readability. + Hexadecimal values a through f are lower case. An example of the string + representation of the UUID is 648a9ca6-1fb4-4f7e-9436-14d015f3dd74 + + @@ -2261,7 +2502,7 @@ 0 - Ignore 1 + Ignore @@ -2269,7 +2510,7 @@ 1 - Cessation Policy 2 + Cessation Policy @@ -2414,7 +2655,7 @@ 0 - Ignore 1 + Ignore @@ -2545,10 +2786,7 @@ 0-31 - Minimum size of RMA in MB - - - + Minimum size of RMA in MB (total bytes = N*(2**20)) @@ -2575,10 +2813,7 @@ RMA size => M% * Partition_memory_size where M is the - value of this 8 bit field - - - + value of this 8 bit field @@ -2611,7 +2846,7 @@ 3 - IBM PowerPC Server Processor Options6 + IBM PowerPC Server Processor Options 1 @@ -2620,7 +2855,7 @@ 0 - Ignore 1 + Ignore @@ -2628,7 +2863,7 @@ 1 - Cessation Policy 2 + Cessation Policy @@ -2755,21 +2990,25 @@ 1 - Cessation Policy 2 + Cessation Policy 2 - - Reserved for Expansion (0b0) + + ibm,change-msi busy: If set, the client program supports RTAS + ibm,change-msi returning a -2 (Call again) or 990x (Extended delay) 3 + + Reserved for Expansion (0b0) + @@ -2817,7 +3056,7 @@ 5 - LoPAR or OF Options 5 + LoPAR or OF Options 1 @@ -2826,7 +3065,7 @@ 0 - Ignore 1 + Ignore @@ -2834,22 +3073,25 @@ 1 - Cessation Policy 2 + Cessation Policy 2 - - Reserved for Expansion (0b0) -   + + 64 bit PE TCEs : If set, the client program supports ibm,query-pe-dma-window + returning a 64-bit value for PE TCEs 3 + + Reserved for Expansion (0b0) + @@ -2881,7 +3123,7 @@ Logical Partitioning: If set the client program supports logical partitioning and associated hcall()s; else the client - program shall be run with the hypervisor bit on.7 + program shall be run with the hypervisor bit on. @@ -2923,7 +3165,7 @@ 4 - Alpha Partition 4 + Alpha Partition @@ -2965,8 +3207,7 @@ value indicates that the client supports the I/O Super Page Option (Support of >4K I/O pages) (Includes extensions to H_MIGRATE_DMA for >4K I/O pages and >256 xlates). - . -   + See . In the ibm,architecture-vec-5 property of the /chosen node, a non-zero value indicates @@ -2981,13 +3222,12 @@ On input to ibm,client-architecture-support this field shall be zero. -   In the ibm,architecture-vec-5 property of the /chosen node, this field represents the implementation dependent number of xlates entries supported per migration operation as: 256 * 2**N. - . + See . @@ -2997,23 +3237,22 @@ On input to ibm,client-architecture-support this field shall be zero. -   In the ibm,architecture-vec-5 property of the /chosen node, this field represents the implementation dependent number of simultaneous migration options supported as: 2**N. - . + See . - + Base   - + 5 - LoPAR or OF Options 5 + LoPAR or OF Options   @@ -3038,8 +3277,7 @@ The value of 1 enables the Extended Cooperative Memory - Over-commit - Option + Over-commit Option @@ -3087,7 +3325,7 @@ - + 6 @@ -3125,7 +3363,7 @@ 3 - Enable Universlly Unique IDentifier Option (UUID) + Reserved for Expansion @@ -3138,7 +3376,24 @@ - 5-7 + 5 + + + Enable Hotplug Interrupts + See Hot Plug Events in . + + + + + 6 + + + Enable Support for Multiple Hotplug Slots per PHB + + + + + 7 Reserved for Expansion @@ -3171,8 +3426,8 @@ 9-12 - Max Processors Supported - (For legacy support, if this byte is not present the + Max Processors Supported + (For legacy support, if this byte is not present the partition is limited to a maximum of 64 processors) @@ -3195,29 +3450,58 @@ Highest Base LoPAR Level Supported as the binary - contents of 13.14 - (i.e. level 4.15 would be encoded as 0x040F) + contents of 13.14 + (i.e. level 4.15 would be encoded as 0x040F) - + 15-16 + + Memory Reference Instrumentation + + + + + 0 + -   + Reference History Array + + + + + 1 - Reserved for Expansion + Access Rate Array + 2 + + + Affinity Domain Access Log + + + + + 3-15 + + + Reserved for Expansion + + + + Base   - + 5 - LoPAR or OF Options 5 + LoPAR or OF Options   @@ -3229,12 +3513,6 @@ - -   - - -   - 0 @@ -3243,12 +3521,6 @@ - -   - - -   - 1 @@ -3257,12 +3529,6 @@ - -   - - -   - 2 @@ -3271,12 +3537,6 @@ - -   - - -   - 3-31 @@ -3286,40 +3546,63 @@ -   + 21 -   + 0-7 - 21 + Sub-Processor Representation Level -- + Defined Values: + 0: Sub-Processors not supported + 1: 1,2,or 4 Sub-Processors supported + 2-255 Reserved + + + + + 22 - 0-7 + 0 - Sub-Processor Representation Level -- - Defined Values: -   - 0: Sub-Processors not supported - 1: 1,2,or 4 Sub-Processors supported - 2-255 Reserved + If set the client program supports the + “ibm,dynamic-memory-v2” + property in the + “ibm,dynamic-reconfiguration-memory” + node and it may be presented in the device tree; + else, the “ibm,dynamic-memory” + property shall be represented. -   + 1 -   + If set the client program supports the + “ibm,drc-info” + property definition and it may be presented in the device tree; + else, the “ibm,drc-indexes”, + “ibm,drc-types”, + “ibm,drc-names”, and + “ibm,drc-power-domains” properies shall be presented. + + - 22-256 + 2-7 -   + Reserved for Expansion + + + 23-256 + + Reserved for Expansion @@ -3436,11 +3719,11 @@ OS Name: Represents the name of the client OS. Defined - values include: - 0x0: Reserved - 0x1: AIX - 0x2: Linux - 0x3-0xFF: Reserved for Expansion + values include: + 0x0: Reserved + 0x1: AIX + 0x2: Linux + 0x3-0xFF: Reserved for Expansion @@ -3496,7 +3779,7 @@ Notes: - + The Ignore Policy bit indicates that the client program assumes all responsibility for the options represented by the option vector. The firmware is to configure the platform at the highest level consistent @@ -3506,7 +3789,7 @@ care). - + The Cessation Policy Bit determines if the partition continues to run if the platform must operate with an option enabled that is not explicitly supported by the client program as represented by the option @@ -3553,7 +3836,7 @@ memory property. - + The Alpha flag only applies to the first partition of a non HMC managed system and activates overrides to the partition's I/O resource allocation as defined in the partition definition. @@ -3589,7 +3872,7 @@ - + Given that the Ignore policy bit is off and the partition continues to run, the options and values presented in by this option vector and supported/chosen by the platform firmware are reported in the @@ -3597,7 +3880,7 @@ /chosen node. - + Option vector number 1 “PowerPC Server Processor Architecture Level” and the property that reports the chosen value (i.e., @@ -3614,7 +3897,7 @@ processor support still exceeds the most restrictive case. - + If a client program does not support logical partitioning no other client programs may be running simultaneously on the platform. The platform may impose further restrictions beyond the scope of LoPAR. If @@ -3651,7 +3934,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be - “rom”. + “rom”. @@ -3967,7 +4250,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be - “rtas”. + “rtas”. @@ -4573,7 +4856,7 @@ property name indicating the platform supports the ibm,change-msi RTAS call with Number of Outputs equal to 4 and - Functions 3 and 4. + Functions 3, 4, and 5. prop-encoded-array: <none> @@ -4830,7 +5113,8 @@ To support dynamic addition and removal of processors, the /cpus - node contains the properties: + node contains either the + ibm,drc-info property or the following set of four properties: ibm,drc-types (cpu), ibm,drc-indexes ibm,drc-names and ibm,drc-power-domains (-1's). These properties have @@ -5051,7 +5335,8 @@ numbers if it expects to make subsequent use of the any RTAS PCI configuration access services. To support dynamic addition and removal of PHBs, the / node - contains the properties: + contains either the + ibm,drc-info property or the following set of four properties: ibm,drc-types (phb), ibm,drc-indexes ibm,drc-names and ibm,drc-power-domains (-1's). These properties have @@ -5232,15 +5517,23 @@ property name indicates the collection of PCI Express link-speed capabilities and measurements at the PE below the PHB. prop-encoded-array: 2 integers encoded with - encode-int. The format of each integer is identical - to the link speed encodings defined in the PCI Express Capability - Structure chapter of the - . In the 2.0 version of that - specification, it defines 0x1 = 2.5 GT/s and 0x2 = 5.0 GT/s. - The first integer represents the maximum PCI Express link-speed at - the Partitionable Endpoint. - The second integer represents the actual PCI Express link-speed at - the Partitionable Endpoint. + encode-int. The value of each integer is + based on which bit is set to reflect link speed according to the Supported Link Speed Vector + segment of the Link Capabilities 2 Register as defined in the PCI Express Capability Structure + chapter of the . In the 3.0 version of that + specification, the supported values are 0x1 (bit 0) = 2.5 GT/s, 0x2 (bit 1) = 5.0 GT/s, and 0x4 (bit 2) = 8.0 GT/s. + + + + + “ibm,max-rtce-mappings” + + property name: for platforms that support the hcall-migrate function + set and more than a single Redirected RDMA mapping per virtual TCE, this property indicates + that there are limits to the number if such multiple Redirected RDMA mappings when used + by children of this PHB as indicated by the property value. + prop-encoded-array: Maximum number of Redirected RTCE mappings encoded as with + encode-int. @@ -5420,8 +5713,8 @@ property name indicates why this PHB's “status” property contains the value of - “reserved” or - “reserved-uninitialized”. + “reserved” or + “reserved-uninitialized”. prop-encoded-array: Text string, encoded as with encode-string. The property value, when present, can have the values specified in @@ -5716,7 +6009,8 @@ memory node that includes dynamic reconfiguration (DR) properties or by an entry in /ibm,dynamic-reconfiguration-memory nodes. To support dynamic addition and removal of regions, the / node - contains the properties: + contains either the + ibm,drc-info property or the following set of four properties: ibm,drc-types (MEM), ibm,drc-indexes ibm,drc-names and ibm,drc-power-domains (-1's). These properties have @@ -5917,7 +6211,7 @@ The following bits in the “flags word” above are defined. - +
Flag Word @@ -6024,10 +6318,14 @@ If b'0', the DRC field of “ibm,dynamic-memory” property - is valid. + is valid or the DRC values for the set of + “ibm,dynamic-memory-v2” + property are valid. If b'1', the DRC field of “ibm,dynamic-memory” property - is invalid. + is invalid or the DRC values for the set of + “ibm,dynamic-memory-v2” + property are invalid. @@ -6040,10 +6338,10 @@ If b'0', the Associativity List Index field of “ibm,dynamic-memory” property - is valid. + or “ibm,dynamic-memory-v2” is valid. If b'1', the Associativity List Index field of “ibm,dynamic-memory” property - is invalid. + or “ibm,dynamic-memory-v2” is invalid. @@ -6068,6 +6366,40 @@ + + “ibm,dynamic-memory-v2” + + + property name that defines memory subject to dynamic + reconfiguration with data in version 2 format. + + prop-encoded-array: The number N of LMB set entries, encoded with + encode-int, + followed by N LMB set entries. + + The number-of-sequential-lmbs encoded with + encode-int. + The number of LMBs in the set. + + The starting-logical-address encoded with + encode-phys. + The logical address of the first LMB in the set. + + The starting-drc-index encoded with + encode-int. + The drc-index of the first LMB in the set. + + The associativity-index encoded with + encode-int. + All LMBs within the set share the same associativity. + + The flags word encoded with + encode-int. + All LMBs within the set share the same flag value. The bits in the flags word are defined in + . + + + “ibm,memory-flags-mask” @@ -6145,7 +6477,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be - “memory-controller”. + “memory-controller”. @@ -6454,7 +6786,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “interrupt-controller”. + “interrupt-controller”. @@ -6467,7 +6799,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be - “PowerPC-External-Interrupt-Presentation”. + “PowerPC-External-Interrupt-Presentation”. @@ -6609,7 +6941,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “interrupt-controller”. + “interrupt-controller”. @@ -6622,12 +6954,10 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this property shall be one of the following: - - “PowerPC-LSI-Source”. - For Level Sensitive Interrupt source controllers. - - “PowerPC-MSI-Source”. - For Message Sensitive Interrupt source controllers such as used + “PowerPC-LSI-Source” + For Level Sensitive Interrupt source controllers. + “PowerPC-MSI-Source” + For Message Sensitive Interrupt source controllers such as used with PCI MSI. @@ -7088,7 +7418,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “event-sources”. + “event-sources”. When events are reported as virtual interrupts there shall be a node of device_type @@ -7179,7 +7509,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “internal-error”. + “internal-error”. @@ -7202,7 +7532,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “epow-events”. + “epow-events”. @@ -7215,7 +7545,7 @@ The presence of the node indicates that all or some of the function has been implemented and will be reported using an interrupt. - “name” S + “name” Standard property name that denotes the I/O sub-system events. @@ -7223,12 +7553,36 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “ibm,io-events”. + “ibm,io-events”. +
+ hot-plug-events + + The presence of the node indicates that all or some of the function + has been implemented and will be reported using an interrupt. + + + + “name” + + Standard + property name that denotes the hot-plug + events. + + prop-encoded-array: A string, encoded as with + encode-string. + The value of this string shall be + “hot-plug-events”. + + + + +
+
@@ -7250,7 +7604,7 @@ prop-encoded-array: A string, encoded as with encode-string. The value of this string shall be - “reserved”. + “reserved”. @@ -7263,7 +7617,7 @@ prop-encoded-array: Text string, encoded as with encode-string. The value of this property shall be - “reserved”. + “reserved”. @@ -7575,6 +7929,50 @@ then used to determine which ILLAN options are implemented. prop-encoded-array: None, this is a name only property. + + + + + “ibm,vf-loc-code” + + Vendor unique property name indicating the physical device + virtual function upon which the vnic-server runs. The value is that of the + “ibm,loc-code” + property of the physical device virtual function. + prop-encoded-array: an arbitrary number of strings, encoded as with + encode-string. + + + + + “ibm,vnic-mode” + + Vendor unique property name that represents the operational + mode in which the vnic-server runs. + prop-encoded-array: a single byte, encoded as with + encode-bytes. + Defined values: + + + 0: backing device is dedicated to one VNIC client + + + 1: backing device is shared by multiple VNIC clients + + + 2-255: reserved + + + + + + + “ibm,vnic-client-mac” + + Vendor unique property name that represents the MAC + address of a given vNIC server's client. + prop-encoded-array: 6 bytes, encoded as with + encode-bytes. @@ -8009,6 +8407,11 @@ ibm,asym-encryption-v# Asymmetric encryption/decryption engine + + + ibm,memory-utilization-instrumentation-v# Memory + usage information + @@ -8156,6 +8559,178 @@ + + + For the memory utilization instrumentation facility node the following properties are defined: + + + + + + “ibm,mui-associativity-mapping” + + property name to define the mapping between Memory Usage + Instrumentation Affinity Log Array entries and their associated associativity strings. + property encoded array: An integer (L) encoded as with + encode-int followed by L sets ALA map entries. + Each ALA map entry consisting of: + + + An integer (ALAentry) encoded as with + encode-int + as would be found in the affinity_log record for the return buffer + from the H_RETURN_PAGEINFO hcall() followed by; + + + + An integer (M) encoded as with + encode-int + that represents the type of source of the reference + (defined values are presented below). Sources of a general + type are grouped together, so that if the + client program does not recognize a given specific type, + it can still categorize via the more general + type of source: + + + + 0-100,000,000 CPU + + + + 100,000,001 – 200,000,000 I/O Bridge + + + + 200,000,001 – 300,000,000 Platform Service Device + + + + All other values reserved (may be grouped together as an unknown source type). + + + Followed by: + + + + An integer (N) encoded as with + encode-int + followed by N associativity lists. + + + + Each associativity list consisting of a number of entries integer (P) encoded as with + encode-int + followed by P integers encoded as with + encode-int + each representing an associativity + domain number. + + + + + + + “ibm,mui-ranges” + + property name to define the implementation specific + ranges of memory utilization instrumentationmeasures. + + property encoded array: An integer (N) encoded as with + encode-int + which communicates the number of pairs of range values, each being an integer encoded as with + encode-int + which represent the implementation limits of a given measure. See + + for details. The reader is to ignore values pairs beyond those it was designed to use. + If the value of N is zero the MUI measures are not available. + + + + +
+ + + <emphasis role="bold"><literal>“ibm,mui-associativity-mapping”</literal></emphasis> range limits + + + + + + + + Pair # + + +   + + +   + + + + + + + 1 + + + MIN/MAX + + + The minimum and maximum supported value of the HUC field + which is the power of 2 multiplier of microseconds that defines the + History Bit Array update period. + + + + + 2 + + + 0/MAX + + + The number of bits implemented in the HBA. + + + + + 3 + + + 0/MAX + + + Access rate in accesses per millisecond. + + + + + 4 + + + 0/MAX + + + Page Age; the MAX value is the number of Page Age Granules + which saturates the page age counter. + + + + + 5 + + + 0/MAX + + + Remote Reference; the MAX value is the number of implemented ALA entries. + + + + +
@@ -9580,8 +10155,9 @@ ibm,dynamic-reconfiguration-memory representation of reconfigurable memory may be used. The default value 0x00000000 indicates the new definition may not be used. The value 0x00000001 indicates the new - definition may be used. All other values are reserved for future - use. + definition may be used. The value 0x00000001 indicates the original version of the new definition may be used. + The value 0x00000002 indicates the version 2 of the new definition may be used. + All other values are reserved for future use. The ns.large-page-ready field is a flag which indicates if the partition OS is prepared to support large pages. The default value diff --git a/Error Handling/bk_main.xml b/Error Handling/bk_main.xml index c5ab023..4dc09e3 100644 --- a/Error Handling/bk_main.xml +++ b/Error Handling/bk_main.xml @@ -42,7 +42,7 @@ OpenPOWER Foundation - Revision 2.0_pre1 + Revision 2.0_pre2 OpenPOWER @@ -70,6 +70,105 @@ + + 2017-10-11 + + + + Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows: + + + ISA 2.07 privileged doorbell extensions (9/16/2012) + + + POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012) + + + Enable Multiple Redirected RDMA mappings per page (3/5/2013) + + + Add Block Invalidate Option (3/5/2013) + + + Implementation Dependent Optimizations (3/13/2013) + + + System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013) + + + New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013) + + + Remove Client-Architecture-Support bit for UUID option (4/16/2013) + + + AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013) + + + Add VNIC Server (5/24/2014) + + + VPA changes for P8 (EBB) (5/24/2013) + + + Add an hcall to clean up the entire MMU hashtable (11/20/2013) + + + Add LPCR[ILE] support to H_SET_MODE (5/31/2013) + + + New Root Node Properties (1/12/2016) + + + Extended Firmware Assisted Dump for P8 Registers (1/24/2014) + + + Sufficient H_COP_OP output buffer (6/21/2014) + + + Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014) + + + Extend H_GET_MPP_X reporting coalesced pages (8/24/2014) + + + Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015) + + + Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015) + + + Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015) + + + Additional System Parameter to read LPAR Name string (10/7/2015) + + + Redesign of properties for DRC information and dynamic memory (7/23/2015) + + + Add additional logical loction code sections (3/4/2016) + + + Add ibm,vnic-client-mac to support vNIC failover (2/29/2016) + + + hcall for registering the process table (3/21/2016) + + + New device tree property for UUID (3/21/2016) + + + Changes for Hotplug RTAS Events (10/24/2016) + + + Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016) + + + + + + 2016-05-04 diff --git a/Error Handling/sec_rtas_error_reporting_return_format.xml b/Error Handling/sec_rtas_error_reporting_return_format.xml index d6819e0..b73b038 100644 --- a/Error Handling/sec_rtas_error_reporting_return_format.xml +++ b/Error Handling/sec_rtas_error_reporting_return_format.xml @@ -466,8 +466,9 @@ later) Dump notification event (228) (for Version 6 or later) + Hot-plug-events (229) (for Version 6 or later)   - Vendor-specific events(229-255): Non-architected + Vendor-specific events(230-255): Non-architected   Other (0): none of the above @@ -634,6 +635,9 @@ For the EPOW Type, the EPOW section must be provided. + + For the HOTPLUG Type, the Hotplug section must be provided. + @@ -1034,6 +1038,19 @@ . + + +   + + + ??? + + + Hotplug Section (ID = “HP”). Optional, present only for + Hotplug event notification. If present, this section follows + Main-B section. See . + + ...- 2047 @@ -4050,6 +4067,217 @@ +
+ Platform Event Log Format, Hotplug Section + + + Platform Error Event Log Format, Version 6, Hotplug Section + + + + + + + + + Offset + + + Length in Bytes + + + Description + + + + + + + 0x00 + + + 2 + + + Section ID: A two-ASCII character field which uniquely + identifies the type of section. Value = “HP”. + + + + + 0x02 + + + 2 + + + Section length: Length in bytes of the section, including + the section ID. + + + + + 0x04 + + + 1 + + + Section Version + + + + + 0x05 + + + 1 + + + Section subType + + + + + 0x06 + + + 2 + + + Creator Component ID + + + + + 0x08 + + + 1 + + + Hotplug Resource Type. + 0x01 = CPU + 0x02 = Memory + 0x03 = SLOT + 0x04 = PHB + 0x05 = PCI + + + + + 0x09 + + + 1 + + + Hotplug Action + 0x01 = Add + 0x02 = Remove + + + + + 0x0A + + + 1 + + + Hotplug Identifier Type + 0x01 = drc name, resource is identified by drc name + 0x02 = drc index, resource is identified by drc index + 0x03 = drc count, number of resources to act upon + 0x04 = drc count indexed, number of resources to act upon beginning at the specified drc index + + + + + + 0x0B + + + 1 + + + Bit + + + Hotplug Event Capability Description + + + + + 0 + + + 1 = Hotplug Token Present + + + + + 1 + + + 0 = Transactional Request: When using “drc count”or “drc count indexed”as the Hotplug + Identifier, the OS should take steps to verify the entirety of the request can be satisfied + before proceeding with the hotplug / unplug operations. If only a partial count can be + satisfied, the OS should ignore the entirety of the request. If the OS cannot determine + this beforehand, it should satisfy the hotplug / unplug request for as many of the + requested resources as possible, and attempt to revert to the original OS / DRC state. + 1 = Non-transactional Request: When using “drc count”or “drc count indexed”as the + Hotplug Identifier, the OS should attempt to satisfy as much of the request as possible, + even if it cannot be satisfied for all the DRCs specified. + + + + + 2:7 + + + Reserved + + + + + + 0x0C + + + Variable + + + Hotplug Identifier + Variable length field depending on the Hotplug Identifier Type specified. + For drc name, this field is a null-terminated ASCII character field containing + the drc name of the resource to hotplug. + For drc index, this is 4 byte field with the drc index of the resource to hotplug. + For drc count, this is a 4 byte field with the number of resources to hotplug. + For drc count indexed, this is two 4 byte fields the first being the number of resources + to hotplug and the second being the drc index at which to start. + + + + + (Section Length - 4) + + + 4 + + + Hotplug Token + Present only if corresponding Hotplug Event Capability bit is set. + Integer value that can be used in conjunction with other fields of the hotplug + event structure (Hotplug Indentifier, Hotplug Type, etc.) to allow OS to associate + hotplug event with the request which generated it for the purposes of providing + feedback to the requestor, such as debugging or error information. + + + + +
+
diff --git a/Error Handling/sec_rtas_hot_plug.xml b/Error Handling/sec_rtas_hot_plug.xml index 696b425..5da520a 100644 --- a/Error Handling/sec_rtas_hot_plug.xml +++ b/Error Handling/sec_rtas_hot_plug.xml @@ -23,11 +23,19 @@ Hot Plug Events - Hot Plug Events, when implemented, are reported through the - event-scan RTAS call. These events are surfaced through the fixed - portions of the RTAS return value. (see - ) Some parts of the system may - be modified without direct support from the OS. + Hot Plug Events, when implemented, are reported through + either the event-scan RTAS call or a hotplug interrupt. + + An OS that wants to be notified of hotplug events will need to + set the appropriate arch-vector bit. Look for the hot-plug-events + node in the /event-sources node of the OF device tree (see + ), enable the interrupts listed + in its “interrupts” property and provide an interrupt handler to call + check-exception when one of those interrupts are received. + + When a hotplug event occurs, whether reported by check-exception + or event-scan, RTAS will directly pass back the Hotplug Event Log as + described in . diff --git a/Platform/bk_main.xml b/Platform/bk_main.xml index 5a2b72c..9493f55 100644 --- a/Platform/bk_main.xml +++ b/Platform/bk_main.xml @@ -42,7 +42,7 @@ OpenPOWER Foundation - Revision 2.0_pre1 + Revision 2.0_pre2 OpenPOWER @@ -71,6 +71,105 @@ + + 2017-10-11 + + + + Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows: + + + ISA 2.07 privileged doorbell extensions (9/16/2012) + + + POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012) + + + Enable Multiple Redirected RDMA mappings per page (3/5/2013) + + + Add Block Invalidate Option (3/5/2013) + + + Implementation Dependent Optimizations (3/13/2013) + + + System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013) + + + New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013) + + + Remove Client-Architecture-Support bit for UUID option (4/16/2013) + + + AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013) + + + Add VNIC Server (5/24/2014) + + + VPA changes for P8 (EBB) (5/24/2013) + + + Add an hcall to clean up the entire MMU hashtable (11/20/2013) + + + Add LPCR[ILE] support to H_SET_MODE (5/31/2013) + + + New Root Node Properties (1/12/2016) + + + Extended Firmware Assisted Dump for P8 Registers (1/24/2014) + + + Sufficient H_COP_OP output buffer (6/21/2014) + + + Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014) + + + Extend H_GET_MPP_X reporting coalesced pages (8/24/2014) + + + Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015) + + + Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015) + + + Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015) + + + Additional System Parameter to read LPAR Name string (10/7/2015) + + + Redesign of properties for DRC information and dynamic memory (7/23/2015) + + + Add additional logical loction code sections (3/4/2016) + + + Add ibm,vnic-client-mac to support vNIC failover (2/29/2016) + + + hcall for registering the process table (3/21/2016) + + + New device tree property for UUID (3/21/2016) + + + Changes for Hotplug RTAS Events (10/24/2016) + + + Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016) + + + + + + 2016-05-04 diff --git a/Platform/ch_product_topology.xml b/Platform/ch_product_topology.xml index 3c734c6..4a2c1b8 100644 --- a/Platform/ch_product_topology.xml +++ b/Platform/ch_product_topology.xml @@ -771,7 +771,7 @@ xml:lang="en"> 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 + 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 @@ -1124,20 +1124,30 @@ xml:lang="en">
Virtual Card Connector Location Codes - Virtual card connector location codes are formed as though there - were a virtual planar with card slots. For example, a virtual IOA would have a - location code of form: + 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 + 5 and in virtual slot 3 would be of the form: - U9117.150.1054321-V5-C2 + U9117.001.1076DEF-V5-C4 + + + 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 + type, model, and serial (the system location code), + not the enclosure type, model, and serial. + + Some operating systems may append a T label + to the virtual IOA location code. For example: + + + U9117.001.1076DEF-V5-C4-T1 - In the virtual card connector location code, the unit location - label specifies the system location code, not the CEC enclosure location - code. - It is recommended that the card connector location label have a - non-zero numeric part, for human factors reasons.
+
Port Location Codes Port location codes are formed by appending the port location @@ -1241,8 +1251,7 @@ xml:lang="en">
- SCSI Device Logical Path Location Codes -- Real and - Virtual + 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 @@ -1255,24 +1264,6 @@ xml:lang="en"> (Decimal L values) - - For virtual SCSI, a 48-bit ID is currently used (but is not limited - from moving to 64-bit) to identify the attached virtualized SCSI device. This - 48/64 bit ID is represented with a -L# in hexadecimal. There is no separate - LUN#. Examples are: - - - U7043.150.1076543-P4-T1-L830000000000 - (Hexadecimal L value) - - - or - - - U7043.150.1076543-P4-T3-W830000000000-L0 - (Hexadecimal W and L values) - -
@@ -1319,7 +1310,7 @@ xml:lang="en">
Fibre Channel Device Logical Path Location Codes -- - Real and Virtual + 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 @@ -1332,15 +1323,6 @@ xml:lang="en"> U787A.001.1012345-P1-C5-T2-W123456789ABCDEF0-L1A05000000000000 - - The same disk being accessed through virtual fibre channel would - appear like: - - - - U9111.520.1012345-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000 - -
@@ -1582,6 +1564,177 @@ xml:lang="en">
+ +
+ Resource Location Codes + + The resource location label consists of the + prefix 'R' followed by a non-zero decimal number. A + resource location code identifies a chip or function + embedded on a FRU. There may be multiple + resources associated with a FRU. The numbering of the + resources on a particular FRU should match + the left to right, top to bottom positioning of the + resources on the FRU when the FRU is in a typical + service position. + + It should be noted that embedded adapters with + internal ports existed prior to introduction of the + resource label. Use of the resource label for unique + partitionable endpoint identification may or may + not be retrofitted to those adapters as they are + carried forward to new platforms. +
+ +
+ Multiple FRUs In The Same Physical Space + + A physical location code is tied to the connector + that a FRU plugs into. If two different parts with + different part numbers can plug into the same connector, + both parts will have the same location code. + However, if two different parts can plug into two + different connectors but share the same physical + space when either is installed, those parts should + each have a different location code. For example, if + two different GX adapters (such as the Bjorn IB adapter + and Newcombe PCI slot riser on Jupiter-IOC) + connect to the same planar using the same connector, + they should both be assigned the same location + code. But if a GX adapter or a PCI adapter can be + installed on a planar, but not both at the same time + as they both can't fit at the same time given the + placement of the connectors on the planar, both slots + should be assigned unique location codes. +
+ +
+ PCI-E Attached I/O Drawers + + A PCI-E attached I/O drawer is an I/O drawer that + attaches to a GX adapter in the CEC via PCI-E + cables (as opposed to RIO or IB cables). There are two + different types of PCI-E attached I/O drawers: + ones where PHB(s) on the GX adapter connect directly + to I/O devices in the drawer and ones where the + PHB(s) on the GX adapter connect to switches (or other + fan-out logic) in the I/O drawer. In the former + case, the partitionable endpoint (PE) is the logical + PHB connection to the device. In the latter case, the + PEs are the slots wired to the downstream switch ports. + + For GX cards whose PHBs connect directly to + devices in the I/O drawer (such as Bluehawk), the + location code and DRC name of the I/O slot partitionable + endpoint will be of the form Ucec-Pw-Cx- + Ty-Lz. Here, Ucec is the type/model/serial of the CEC + that contains the GX adapter, Pw is the planar + that contains the GX adapter, Cx is the GX adapter, + Ty is one of the ports on the adapter, and Lz is a + logical label representing a logical PCI-e connection + to an I/O device at the other end of the PCI-e + cable plugged into that port (note that there may be + multiple Cx labels if the GX adapter doesn't plug + directly into the planar in the system in question). + This location code and DRC name will be generated + by system firmware for each PE on each GX adapter that + is installed in the system and that supports + direct-connect drawers (i.e. drawers without a PCI-E + switch in them). The location code and DRC + name will be generated regardless of whether or not a + PCI-E cable is attached to the GX adapter. + It is permissible to append additional labels beyond + the L label to create different location codes for + FRUs/devices downstream from the I/O device in the + drawer that is attached to the PCI-e cable. It is + not required that all subsequent labels be logical labels. + + For GX cards whose ports connect to a PCI-E switch + in an I/O drawer via PCI-E cables, the location + code format has not yet been defined. +
+ +
+ Virtual SCSI (vSCSI) Device Location Codes + + The location code for a virtual SCSI (vSCSI) + device is formed by appending an L label to the location + code of the parent virtual IOA. The L label contains a + 48 or 64 bit hexadecimal value that uniquely + identifies the virtualized SCSI device. A virtual + SCSI device attached to a virtual IOA at + U9119.MME.1085B17-V4-C5-T1 would have a location code of the form: + U9119.MME.1085B17-V4-C5-T1-L8100000000000000 + Note that some old pSeries firmware may represent + the virtualized device identifier as + W8100000000000000-L0 rather than simply L8100000000000000. This approach was abandoned in + late 2008. + + See for a description of the + virtual IOA location code. +
+ +
+ Virtual Fibre Channel Device Location Codes + + The location code for a virtual fibre channel device + is formed by appending the worldwide unique port + identifier (W label) and LUN (L label) to the location + code of the parent virtual IOA. The values of + the L and W labels are both in hexadecimal. A fibre + channel disk attached to a virtual IOA at + U9119.MME.1085B17-V4-C5-T1 would have a location + code of the form: + + + + U9119.MME.1085B17-V2-C4-T1-W123456789ABCDEF0-L1A05000000000000 + + + + See for a description of the + virtual IOA location code. +
+ +
+ NVMe Device Logical Path Location Codes + + Non-volatile memory (NVM) devices that are + not mounted/docked on a backplane that supports + location code VPD will have location codes composed + of the location code of the controlling IOA + followed by a L label. The number value of L label + is a decimal value, and it is the unique NVMe + namespace identifier. An NVMe device controlled by + an IOA at U787A.001.1012345-P1-C5 would + have a location code of the form: + + + + U787A.001.1012345-P1-C5-L3 + + +
+ +
+ Virtual Coherent Accelerator (CAPI) Function Location Codes + + The location code for a virtual coherent accelerator + (CA) function is formed by appending two S labels, + the first specifying the identifier of the physical + function and the second specifying the identifier of the + logical function, both in decimal, to the location code of + the physical CAPI adapter. A virtual CA + function associated with physical function 1 and logical + function 2 on the CAPI adapter at location + U78CA.001.1234567-P1-C4-C1 would have location code: + + + + U78CA.001.1234567-P1-C4-C1-S1-S2 + + +
@@ -2954,6 +3107,27 @@ xml:lang="en"> Model Number: 3 characters with a leading blank. + + + ME + + + ASCII + + + 8 + + + -- + + + 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 + ME date are not entitled to be flashed on that system. + Format:yyyymmdd + + MF @@ -2973,6 +3147,25 @@ xml:lang="en"> keyword. + + + MG + + + ASCII + + + 8 + + + -- + + + Microcode General Availability/Release Date + This is the date the system firmware image was released and published for customer use. + Format:yyyymmdd + + MI diff --git a/Platform/ch_system_reqs.xml b/Platform/ch_system_reqs.xml index fe1d518..d38d6cd 100644 --- a/Platform/ch_system_reqs.xml +++ b/Platform/ch_system_reqs.xml @@ -2460,7 +2460,7 @@ ELSE - + for information on ibm,partition-uuid. @@ -2493,6 +2493,64 @@ ELSE functions see + + + Memory Usage Instrumentation Option (MUI) + + + O + + + O + + + See . + + + + + Block Invalidate Option + + + O + + + O + + + Allows improved performance for removing page table entries representing a naturally aligned + block of virtual addresses. + + + + + Energy Management Tuning Parameters (EMTP) + + + O + + + O + + + Reports the system Energy Management tuning values. + + + + + In-Memory Table Translation Option + + + O + + + O + + + Provides support for the system wide Memory Management Unit + architecture introduced in POWER ISA 3.0 + + diff --git a/README.md b/README.md index 2905127..0e1bc0b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # Linux Architecture Reference Specification for OpenPOWER -This repository hold the source for the source for the +This repository holds the source for the Linux on Power Architecture Reference documents. There are multiple component documents as follows: diff --git a/RTAS/bk_main.xml b/RTAS/bk_main.xml index df88260..c7b69d0 100644 --- a/RTAS/bk_main.xml +++ b/RTAS/bk_main.xml @@ -42,7 +42,7 @@ OpenPOWER Foundation - Revision 2.0_pre1 + Revision 2.0_pre2 OpenPOWER @@ -72,6 +72,105 @@ + 2017-10-11 + + + + Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows: + + + ISA 2.07 privileged doorbell extensions (9/16/2012) + + + POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012) + + + Enable Multiple Redirected RDMA mappings per page (3/5/2013) + + + Add Block Invalidate Option (3/5/2013) + + + Implementation Dependent Optimizations (3/13/2013) + + + System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013) + + + New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013) + + + Remove Client-Architecture-Support bit for UUID option (4/16/2013) + + + AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013) + + + Add VNIC Server (5/24/2014) + + + VPA changes for P8 (EBB) (5/24/2013) + + + Add an hcall to clean up the entire MMU hashtable (11/20/2013) + + + Add LPCR[ILE] support to H_SET_MODE (5/31/2013) + + + New Root Node Properties (1/12/2016) + + + Extended Firmware Assisted Dump for P8 Registers (1/24/2014) + + + Sufficient H_COP_OP output buffer (6/21/2014) + + + Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014) + + + Extend H_GET_MPP_X reporting coalesced pages (8/24/2014) + + + Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015) + + + Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015) + + + Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015) + + + Additional System Parameter to read LPAR Name string (10/7/2015) + + + Redesign of properties for DRC information and dynamic memory (7/23/2015) + + + Add additional logical loction code sections (3/4/2016) + + + Add ibm,vnic-client-mac to support vNIC failover (2/29/2016) + + + hcall for registering the process table (3/21/2016) + + + New device tree property for UUID (3/21/2016) + + + Changes for Hotplug RTAS Events (10/24/2016) + + + Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016) + + + + + + +R 2016-05-04 diff --git a/RTAS/ch_firmware_dump.xml b/RTAS/ch_firmware_dump.xml index 7d2a22b..48b3025 100644 --- a/RTAS/ch_firmware_dump.xml +++ b/RTAS/ch_firmware_dump.xml @@ -31,7 +31,9 @@ The register save area is an area in the partition’s memory used to preserve the registers for the active CPUs during a firmware assisted dump. The location and size of this area is specified by the - partition when firmware assisted dump. The minimum size will be sent to the + partition when firmware assisted dumpwhen it registers for firmware + assisted dump using the . + The minimum size will be sent to the partition in the PFDS KDUMP node. The register save is a semi-free format list of registers for each CPU. Each list of registers for a CPU starts with “CPUSTRT” and @@ -57,6 +59,14 @@ required to be in any specific order (To make debug easier they will most likely be placed in ascending ASCII identifier order) + + + If the CPU is in a Transactional Memory operating mode such + that there is a valid register check point, the contents of that register + checkpoint is included with register identifiers starting with “X-”, see + , + else the checkpoint registers are not included. + @@ -426,13 +436,13 @@
  - +
Identifiers Supported in Version 0x0 of the Table - - - + + + @@ -3775,6 +3785,2173 @@ Fixed-Point Exception Register + + + 0x4653435200000000 + + + FSCR + + + Facility Status and Control Register + + + + + 0x5654420000000000 + + + VTB + + + Virtual Time Base + + + + + 0x4943000000000000 + + + IC + + + Instruction Counter + + + + + 0x4441575230000000 + + + DAWR0 + + + Data Address Watchpoint Register 0 + + + + + 0x4441575258300000 + + + DAWRX0 + + + Data Address Watchpoint Register Extension 0 + + + + + 0x4349414252000000 + + + CIABR + + + Completed Instruction Address Breakpoint Register + + + + + 0x5441520000000000 + + + TAR + + + Target Address Register + + + + + 0x4245534352000000 + + + BESCR + + + Branch Event Status and Control Register + + + + + 0x4542424852000000 + + + EBBHR + + + Event Based Branch Handler Register + + + + + 0x4542425252000000 + + + EBBRR + + + Event Based Branch Return Register + + + + + 0x49414D5200000000 + + + IAMR + + + Instruction Authority Mask Register + + + + + 0x5053504200000000 + + + PSPB + + + Problem State Priority Boost Register + + + + + 0x5250520000000000 + + + RPR + + + Relative Priority Register + + + + + 0x4D4D435232000000 + + + MMCR2 + + + Monitor Mode Control Register 2 + + + + + 0x5349455200000000 + + + SIER + + + Sampled Instruction Event Register + + + + + 0x4450444553000000 + + + DPDES + + + Directed Priviledged Doorbell State + + + + + 0x5449520000000000 + + + TIR + + + Physical Thread Identification Register + + + + + 0x5449440000000000 + + + TID + + + Logical Thread Identification Register + + + + + 0x53504D4331000000 + + + SPMC1 + + + Supervisor Performance Monitor Counter 1 + + + + + 0x53504D4332000000 + + + SPMC2 + + + Supervisor Performance Monitor Counter 2 + + + + + 0x4D4D435253000000 + + + MMCRS + + + Monitor Mode Control Register S + + + + + 0x574F524300000000 + + + WORC + + + Workload Optimization Register Core + + + + + 0x574F525400000000 + + + WORT + + + Workload Optimization Register Thread + + + + + 0x5446484152000000 + + + TFHAR + + + Transaction Failure Handler Address Register + + + + + 0x5446494152000000 + + + TFIAR + + + Transaction Failure Instruction Address Register + + + + + 0x5445584153520000 + + + TEXASR + + + Transaction Exception And Summary Register + + + + + 0x582D435200000000 + + + X-CR + + + Transaction Checkpoint Condition Register + + + + + 0x582D565343520000 + + + X-VSCR + + + Transaction Checkpoint VMX Status and Condition Register + + + + + 0x582D584552000000 + + + X-XER + + + Transaction Checkpoint Fixed-Point Exception Register + + + + + 0x582D4C5200000000 + + + X-LR + + + Transaction Checkpoint Link Register + + + + + 0x582D435452000000 + + + X-CTR + + + Transaction Checkpoint Count Register + + + + + 0x582D465053435200 + + + X-FPSCR + + + Transaction Checkpoint Floating Point Status and Control Register + + + + + 0x582D414D52000000 + + + X-AMR + + + Transaction Checkpoint Authority Mask Register + + + + + 0x582D545352000000 + + + X-TSR + + + Transaction Checkpoint Thread Status Register + + + + + 0x582D565253415645 + + + X-VRSAVE + + + Transaction Checkpoint VR Save Register + + + + + 0x582D445343520000 + + + X-DSCR + + + Transaction Checkpoint Depth Stream Control Register + + + + + 0x582D544152000000 + + + X-TAR + + + Transaction Checkpoint Target Address Register + + + + + 0x582D475052303000 + + + X-GPR00 + + + Transaction Checkpoint General Purpose Register 0 + + + + + 0x582D475052303100 + + + X-GPR01 + + + Transaction Checkpoint General Purpose Register 1 + + + + + 0x582D475052303200 + + + X-GPR02 + + + Transaction Checkpoint General Purpose Register 2 + + + + + 0x582D475052303300 + + + X-GPR03 + + + Transaction Checkpoint General Purpose Register 3 + + + + + 0x582D475052303400 + + + X-GPR04 + + + Transaction Checkpoint General Purpose Register 4 + + + + + 0x582D475052303500 + + + X-GPR05 + + + Transaction Checkpoint General Purpose Register 5 + + + + + 0x582D475052303600 + + + X-GPR06 + + + Transaction Checkpoint General Purpose Register 6 + + + + + 0x582D475052303700 + + + X-GPR07 + + + Transaction Checkpoint General Purpose Register 7 + + + + + 0x582D475052303800 + + + X-GPR08 + + + Transaction Checkpoint General Purpose Register 8 + + + + + 0x582D475052303900 + + + X-GPR09 + + + Transaction Checkpoint General Purpose Register 9 + + + + + 0x582D475052313000 + + + X-GPR10 + + + Transaction Checkpoint General Purpose Register 10 + + + + + 0x582D475052313100 + + + X-GPR11 + + + Transaction Checkpoint General Purpose Register 11 + + + + + 0x582D475052313200 + + + X-GPR12 + + + Transaction Checkpoint General Purpose Register 12 + + + + + 0x582D475052313300 + + + X-GPR13 + + + Transaction Checkpoint General Purpose Register 13 + + + + + 0x582D475052313400 + + + X-GPR14 + + + Transaction Checkpoint General Purpose Register 14 + + + + + 0x582D475052313500 + + + X-GPR15 + + + Transaction Checkpoint General Purpose Register 15 + + + + + 0x582D475052313600 + + + X-GPR16 + + + Transaction Checkpoint General Purpose Register 16 + + + + + 0x582D475052313700 + + + X-GPR17 + + + Transaction Checkpoint General Purpose Register 17 + + + + + 0x582D475052313800 + + + X-GPR18 + + + Transaction Checkpoint General Purpose Register 18 + + + + + 0x582D475052313900 + + + X-GPR19 + + + Transaction Checkpoint General Purpose Register 19 + + + + + 0x582D475052323000 + + + X-GPR20 + + + Transaction Checkpoint General Purpose Register 20 + + + + + 0x582D475052323100 + + + X-GPR21 + + + Transaction Checkpoint General Purpose Register 21 + + + + + 0x582D475052323200 + + + X-GPR22 + + + Transaction Checkpoint General Purpose Register 22 + + + + + 0x582D475052323300 + + + X-GPR23 + + + Transaction Checkpoint General Purpose Register 23 + + + + + 0x582D475052323400 + + + X-GPR24 + + + Transaction Checkpoint General Purpose Register 24 + + + + + 0x582D475052323500 + + + X-GPR25 + + + Transaction Checkpoint General Purpose Register 25 + + + + + 0x582D475052323600 + + + X-GPR26 + + + Transaction Checkpoint General Purpose Register 26 + + + + + 0x582D475052323700 + + + X-GPR27 + + + Transaction Checkpoint General Purpose Register 27 + + + + + 0x582D475052323800 + + + X-GPR28 + + + Transaction Checkpoint General Purpose Register 28 + + + + + 0x582D475052323900 + + + X-GPR29 + + + Transaction Checkpoint General Purpose Register 29 + + + + + 0x582D475052333000 + + + X-GPR30 + + + Transaction Checkpoint General Purpose Register 30 + + + + + 0x582D475052333100 + + + X-GPR31 + + + Transaction Checkpoint General Purpose Register 31 + + + + + 0x582D565330304849 + + + X-VS00HI + + + Transaction Checkpoint Vector Scalar Register 0 High + + + + + 0x582D565330304C4F + + + X-VS00LO + + + Transaction Checkpoint Vector Scalar Register 0 Low + + + + + 0x582D565330314849 + + + X-VS01HI + + + Transaction Checkpoint Vector Scalar Register 1 High + + + + + 0x582D565330314C4F + + + X-VS01LO + + + Transaction Checkpoint Vector Scalar Register 1 Low + + + + + 0x582D565330324849 + + + X-VS02HI + + + Transaction Checkpoint Vector Scalar Register 2 High + + + + + 0x582D565330324C4F + + + X-VS02LO + + + Transaction Checkpoint Vector Scalar Register 2 Low + + + + + 0x582D565330334849 + + + X-VS03HI + + + Transaction Checkpoint Vector Scalar Register 3 High + + + + + 0x582D565330334C4F + + + X-VS03LO + + + Transaction Checkpoint Vector Scalar Register 3 Low + + + + + 0x582D565330344849 + + + X-VS04HI + + + Transaction Checkpoint Vector Scalar Register 4 High + + + + + 0x582D565330344C4F + + + X-VS04LO + + + Transaction Checkpoint Vector Scalar Register 4 Low + + + + + 0x582D565330354849 + + + X-VS05HI + + + Transaction Checkpoint Vector Scalar Register 5 High + + + + + 0x582D565330354C4F + + + X-VS05LO + + + Transaction Checkpoint Vector Scalar Register 5 Low + + + + + 0x582D565330364849 + + + X-VS06HI + + + Transaction Checkpoint Vector Scalar Register 6 High + + + + + 0x582D565330364C4F + + + X-VS06LO + + + Transaction Checkpoint Vector Scalar Register 6 Low + + + + + 0x582D565330374849 + + + X-VS07HI + + + Transaction Checkpoint Vector Scalar Register 7 High + + + + + 0x582D565330374C4F + + + X-VS07LO + + + Transaction Checkpoint Vector Scalar Register 7 Low + + + + + 0x582D565330384849 + + + X-VS08HI + + + Transaction Checkpoint Vector Scalar Register 8 High + + + + + 0x582D565330384C4F + + + X-VS08LO + + + Transaction Checkpoint Vector Scalar Register 8 Low + + + + + 0x582D565330394849 + + + X-VS09HI + + + Transaction Checkpoint Vector Scalar Register 9 High + + + + + 0x582D565330394C4F + + + X-VS09LO + + + Transaction Checkpoint Vector Scalar Register 9 Low + + + + + 0x582D565331304849 + + + X-VS10HI + + + Transaction Checkpoint Vector Scalar Register 10 High + + + + + 0x582D565331304C4F + + + X-VS10LO + + + Transaction Checkpoint Vector Scalar Register 10 Low + + + + + 0x582D565331314849 + + + X-VS11HI + + + Transaction Checkpoint Vector Scalar Register 11 High + + + + + 0x582D565331314C4F + + + X-VS11LO + + + Transaction Checkpoint Vector Scalar Register 11 Low + + + + + 0x582D565331324849 + + + X-VS12HI + + + Transaction Checkpoint Vector Scalar Register 12 High + + + + + 0x582D565331324C4F + + + X-VS12LO + + + Transaction Checkpoint Vector Scalar Register 12 Low + + + + + 0x582D565331334849 + + + X-VS13HI + + + Transaction Checkpoint Vector Scalar Register 13 High + + + + + 0x582D565331334C4F + + + X-VS13LO + + + Transaction Checkpoint Vector Scalar Register 13 Low + + + + + 0x582D565331344849 + + + X-VS14HI + + + Transaction Checkpoint Vector Scalar Register 14 High + + + + + 0x582D565331344C4F + + + X-VS14LO + + + Transaction Checkpoint Vector Scalar Register 14 Low + + + + + 0x582D565331354849 + + + X-VS15HI + + + Transaction Checkpoint Vector Scalar Register 15 High + + + + + 0x582D565331354C4F + + + X-VS15LO + + + Transaction Checkpoint Vector Scalar Register 15 Low + + + + + 0x582D565331364849 + + + X-VS16HI + + + Transaction Checkpoint Vector Scalar Register 16 High + + + + + 0x582D565331364C4F + + + X-VS16LO + + + Transaction Checkpoint Vector Scalar Register 16 Low + + + + + 0x582D565331374849 + + + X-VS17HI + + + Transaction Checkpoint Vector Scalar Register 17 High + + + + + 0x582D565331374C4F + + + X-VS17LO + + + Transaction Checkpoint Vector Scalar Register 17 Low + + + + + 0x582D565331384849 + + + X-VS18HI + + + Transaction Checkpoint Vector Scalar Register 18 High + + + + + 0x582D565331384C4F + + + X-VS18LO + + + Transaction Checkpoint Vector Scalar Register 18 Low + + + + + 0x582D565331394849 + + + X-VS19HI + + + Transaction Checkpoint Vector Scalar Register 19 High + + + + + 0x582D565331394C4F + + + X-VS19LO + + + Transaction Checkpoint Vector Scalar Register 19 Low + + + + + 0x582D565332304849 + + + X-VS20HI + + + Transaction Checkpoint Vector Scalar Register 20 High + + + + + 0x582D565332304C4F + + + X-VS20LO + + + Transaction Checkpoint Vector Scalar Register 20 Low + + + + + 0x582D565332314849 + + + X-VS21HI + + + Transaction Checkpoint Vector Scalar Register 21 High + + + + + 0x582D565332314C4F + + + X-VS21LO + + + Transaction Checkpoint Vector Scalar Register 21 Low + + + + + 0x582D565332324849 + + + X-VS22HI + + + Transaction Checkpoint Vector Scalar Register 22 High + + + + + 0x582D565332324C4F + + + X-VS22LO + + + Transaction Checkpoint Vector Scalar Register 22 Low + + + + + 0x582D565332334849 + + + X-VS23HI + + + Transaction Checkpoint Vector Scalar Register 23 High + + + + + 0x582D565332334C4F + + + X-VS23LO + + + Transaction Checkpoint Vector Scalar Register 23 Low + + + + + 0x582D565332344849 + + + X-VS24HI + + + Transaction Checkpoint Vector Scalar Register 24 High + + + + + 0x582D565332344C4F + + + X-VS24LO + + + Transaction Checkpoint Vector Scalar Register 24 Low + + + + + 0x582D565332354849 + + + X-VS25HI + + + Transaction Checkpoint Vector Scalar Register 25 High + + + + + 0x582D565332354C4F + + + X-VS25LO + + + Transaction Checkpoint Vector Scalar Register 25 Low + + + + + 0x582D565332364849 + + + X-VS26HI + + + Transaction Checkpoint Vector Scalar Register 26 High + + + + + 0x582D565332364C4F + + + X-VS26LO + + + Transaction Checkpoint Vector Scalar Register 26 Low + + + + + 0x582D565332374849 + + + X-VS27HI + + + Transaction Checkpoint Vector Scalar Register 27 High + + + + + 0x582D565332374C4F + + + X-VS27LO + + + Transaction Checkpoint Vector Scalar Register 27 Low + + + + + 0x582D565332384849 + + + X-VS28HI + + + Transaction Checkpoint Vector Scalar Register 28 High + + + + + 0x582D565332384C4F + + + X-VS28LO + + + Transaction Checkpoint Vector Scalar Register 28 Low + + + + + 0x582D565332394849 + + + X-VS29HI + + + Transaction Checkpoint Vector Scalar Register 29 High + + + + + 0x582D565332394C4F + + + X-VS29LO + + + Transaction Checkpoint Vector Scalar Register 29 Low + + + + + 0x582D565333304849 + + + X-VS30HI + + + Transaction Checkpoint Vector Scalar Register 30 High + + + + + 0x582D565333304C4F + + + X-VS30LO + + + Transaction Checkpoint Vector Scalar Register 30 Low + + + + + 0x582D565333314849 + + + X-VS31HI + + + Transaction Checkpoint Vector Scalar Register 31 High + + + + + 0x582D565333314C4F + + + X-VS31LO + + + Transaction Checkpoint Vector Scalar Register 31 Low + + + + + 0x582D565333324849 + + + X-VS32HI + + + Transaction Checkpoint Vector Scalar Register 32 High + + + + + 0x582D565333324C4F + + + X-VS32LO + + + Transaction Checkpoint Vector Scalar Register 32 Low + + + + + 0x582D565333334849 + + + X-VS33HI + + + Transaction Checkpoint Vector Scalar Register 33 High + + + + + 0x582D565333334C4F + + + X-VS33LO + + + Transaction Checkpoint Vector Scalar Register 33 Low + + + + + 0x582D565333344849 + + + X-VS34HI + + + Transaction Checkpoint Vector Scalar Register 34 High + + + + + 0x582D565333344C4F + + + X-VS34LO + + + Transaction Checkpoint Vector Scalar Register 34 Low + + + + + 0x582D565333354849 + + + X-VS35HI + + + Transaction Checkpoint Vector Scalar Register 35 High + + + + + 0x582D565333354C4F + + + X-VS35LO + + + Transaction Checkpoint Vector Scalar Register 35 Low + + + + + 0x582D565333364849 + + + X-VS36HI + + + Transaction Checkpoint Vector Scalar Register 36 High + + + + + 0x582D565333364C4F + + + X-VS36LO + + + Transaction Checkpoint Vector Scalar Register 36 Low + + + + + 0x582D565333374849 + + + X-VS37HI + + + Transaction Checkpoint Vector Scalar Register 37 High + + + + + 0x582D565333374C4F + + + X-VS37LO + + + Transaction Checkpoint Vector Scalar Register 37 Low + + + + + 0x582D565333384849 + + + X-VS38HI + + + Transaction Checkpoint Vector Scalar Register 38 High + + + + + 0x582D565333384C4F + + + X-VS38LO + + + Transaction Checkpoint Vector Scalar Register 38 Low + + + + + 0x582D565333394849 + + + X-VS39HI + + + Transaction Checkpoint Vector Scalar Register 39 High + + + + + 0x582D565333394C4F + + + X-VS39LO + + + Transaction Checkpoint Vector Scalar Register 39 Low + + + + + 0x582D565334304849 + + + X-VS40HI + + + Transaction Checkpoint Vector Scalar Register 40 High + + + + + 0x582D565334304C4F + + + X-VS40LO + + + Transaction Checkpoint Vector Scalar Register 40 Low + + + + + 0x582D565334314849 + + + X-VS41HI + + + Transaction Checkpoint Vector Scalar Register 41 High + + + + + 0x582D565334314C4F + + + X-VS41LO + + + Transaction Checkpoint Vector Scalar Register 41 Low + + + + + 0x582D565334324849 + + + X-VS42HI + + + Transaction Checkpoint Vector Scalar Register 42 High + + + + + 0x582D565334324C4F + + + X-VS42LO + + + Transaction Checkpoint Vector Scalar Register 42 Low + + + + + 0x582D565334334849 + + + X-VS43HI + + + Transaction Checkpoint Vector Scalar Register 43 High + + + + + 0x582D565334334C4F + + + X-VS43LO + + + Transaction Checkpoint Vector Scalar Register 43 Low + + + + + 0x582D565334344849 + + + X-VS44HI + + + Transaction Checkpoint Vector Scalar Register 44 High + + + + + 0x582D565334344C4F + + + X-VS44LO + + + Transaction Checkpoint Vector Scalar Register 44 Low + + + + + 0x582D565334354849 + + + X-VS45HI + + + Transaction Checkpoint Vector Scalar Register 45 High + + + + + 0x582D565334354C4F + + + X-VS45LO + + + Transaction Checkpoint Vector Scalar Register 45 Low + + + + + 0x582D565334364849 + + + X-VS46HI + + + Transaction Checkpoint Vector Scalar Register 46 High + + + + + 0x582D565334364C4F + + + X-VS46LO + + + Transaction Checkpoint Vector Scalar Register 46 Low + + + + + 0x582D565334374849 + + + X-VS47HI + + + Transaction Checkpoint Vector Scalar Register 47 High + + + + + 0x582D565334374C4F + + + X-VS47LO + + + Transaction Checkpoint Vector Scalar Register 47 Low + + + + + 0x582D565334384849 + + + X-VS48HI + + + Transaction Checkpoint Vector Scalar Register 48 High + + + + + 0x582D565334384C4F + + + X-VS48LO + + + Transaction Checkpoint Vector Scalar Register 48 Low + + + + + 0x582D565334394849 + + + X-VS49HI + + + Transaction Checkpoint Vector Scalar Register 49 High + + + + + 0x582D565334394C4F + + + X-VS49LO + + + Transaction Checkpoint Vector Scalar Register 49 Low + + + + + 0x582D565335304849 + + + X-VS50HI + + + Transaction Checkpoint Vector Scalar Register 50 High + + + + + 0x582D565335304C4F + + + X-VS50LO + + + Transaction Checkpoint Vector Scalar Register 50 Low + + + + + 0x582D565335314849 + + + X-VS51HI + + + Transaction Checkpoint Vector Scalar Register 51 High + + + + + 0x582D565355314C4F + + + X-VS51LO + + + Transaction Checkpoint Vector Scalar Register 51 Low + + + + + 0x582D565335324849 + + + X-VS52HI + + + Transaction Checkpoint Vector Scalar Register 52 High + + + + + 0x582D565335324C4F + + + X-VS52LO + + + Transaction Checkpoint Vector Scalar Register 52 Low + + + + + 0x582D565335334849 + + + X-VS53HI + + + Transaction Checkpoint Vector Scalar Register 53 High + + + + + 0x582D565335334C4F + + + X-VS53LO + + + Transaction Checkpoint Vector Scalar Register 53 Low + + + + + 0x582D565335344849 + + + X-VS54HI + + + Transaction Checkpoint Vector Scalar Register 54 High + + + + + 0x582D565335344C4F + + + X-VS54LO + + + Transaction Checkpoint Vector Scalar Register 54 Low + + + + + 0x582D565335354849 + + + X-VS55HI + + + Transaction Checkpoint Vector Scalar Register 55 High + + + + + 0x582D565335354C4F + + + X-VS55LO + + + Transaction Checkpoint Vector Scalar Register 55 Low + + + + + 0x582D565335364849 + + + X-VS56HI + + + Transaction Checkpoint Vector Scalar Register 56 High + + + + + 0x582D565335364C4F + + + X-VS56LO + + + Transaction Checkpoint Vector Scalar Register 56 Low + + + + + 0x582D565335374849 + + + X-VS57HI + + + Transaction Checkpoint Vector Scalar Register 57 High + + + + + 0x582D565335374C4F + + + X-VS57LO + + + Transaction Checkpoint Vector Scalar Register 57 Low + + + + + 0x582D565335384849 + + + X-VS58HI + + + Transaction Checkpoint Vector Scalar Register 58 High + + + + + 0x582D565335384C4F + + + X-VS58LO + + + Transaction Checkpoint Vector Scalar Register 58 Low + + + + + 0x582D565335394849 + + + X-VS59HI + + + Transaction Checkpoint Vector Scalar Register 59 High + + + + + 0x582D565335394C4F + + + X-VS59LO + + + Transaction Checkpoint Vector Scalar Register 59 Low + + + + + 0x582D565336304849 + + + X-VS60HI + + + Transaction Checkpoint Vector Scalar Register 60 High + + + + + 0x582D565336304C4F + + + X-VS60LO + + + Transaction Checkpoint Vector Scalar Register 60 Low + + + + + 0x582D565336314849 + + + X-VS61HI + + + Transaction Checkpoint Vector Scalar Register 61 High + + + + + 0x582D565336314C4F + + + X-VS61LO + + + Transaction Checkpoint Vector Scalar Register 61 Low + + + + + 0x582D565336324849 + + + X-VS62HI + + + Transaction Checkpoint Vector Scalar Register 62 High + + + + + 0x582D565336324C4F + + + X-VS62LO + + + Transaction Checkpoint Vector Scalar Register 62 Low + + + + + 0x582D565336334849 + + + X-VS63HI + + + Transaction Checkpoint Vector Scalar Register 63 High + + + + + 0x582D565336334C4F + + + X-VS63LO + + + Transaction Checkpoint Vector Scalar Register 63 Low + +
diff --git a/RTAS/ch_rtas_call_defn.xml b/RTAS/ch_rtas_call_defn.xml index c0e3942..5dc6a71 100644 --- a/RTAS/ch_rtas_call_defn.xml +++ b/RTAS/ch_rtas_call_defn.xml @@ -8793,24 +8793,40 @@ - “MI” <sp> current-T-image <sp> + “MI”<sp> current-T-image <sp> current-P-image <0x0A> - “MI” <sp> new-T-image <sp> new-P-image + “MI”<sp> new-T-image <sp> new-P-image <0x00> - “ML” <sp> current-T-image + “ML”<sp> current-T-image <sp> current-P-image <0x0A> - “ML” <sp> new-T-image <sp> + “ML”<sp> new-T-image <sp> new-P-image <0x00> + + + “MG”<sp>current-T-img-ga-date<sp>current-P-img-ga-date<0x0A> + + + + “MG”<sp>new-T-img-ga-date<sp>new-P-img-ga-date<0x0A> + + + + “MG”<sp>input-image-ga-date<0x0A> + + + + “ME”<sp>fw-service-entitlement-expiration-date<0x00> + In Requirement @@ -8915,6 +8931,16 @@ T side will be updated with a downlevel image + + + 7 + + + No update done, the candidate image's release date is later + than the system's firmware service entitlement date - service + warranty period has expired + + 0 @@ -11442,7 +11468,7 @@ specifies that the platform implements the version of this RTAS call that allows Number Outputs equal to 4 and - Functions 3 and 4. + Functions 3, 4 and 5. If the ibm,change-msi RTAS call is made with Number Outputs equal to 4 or with @@ -11475,8 +11501,7 @@ . - Argument Call Buffer - <emphasis>ibm,change-msi</emphasis> + <emphasis>ibm,change-msi</emphasis> Argument Call Buffer @@ -11607,6 +11632,11 @@ “ibm,change-msix-capable” exists): Request to set to a new number of MSI-X interrupts (including set to 0) + 5: (Only valid if + + “ibm,change-msix-capable” exists): + Request to set to a new number of 32 bit MSI (including set to 0) + disregarding the adapter capability to support 64 bit MSI. @@ -11620,8 +11650,7 @@ configuration address. A value of 0 is specified in order to remove all MSIs for the PCI configuration address. This input parameter is ignored by RTAS for - Function values other than 1, 3, or - 4. + Function values other than 1, 3, 4 or 5. @@ -11943,6 +11972,13 @@ ibm,change-msi to increase the number of interrupts may produce a greater number of interrupts. + + + The platform will return a status -2 or 990x only when the OS + indicates support. The OS indicates support via ibm,client-architecture-support, + vector 4. See section on "Root Node Methods" + for more information. + @@ -18905,15 +18941,13 @@ 48 - UUID + Reserved - 16 Byte String +   - - - +     @@ -18921,7 +18955,130 @@ - >48 + 49 + + + Reserved + + +   + + +   + + +   + + + + + 50 + + + TLB Block Invalidate Characteristics + + + Variable Length Series of Bytes + + + See + + +   + + + + + 51 + + + Reserved + + +   + + +   + + +   + + + + + 52 + + + Energy Management Tuning Parameters + + + Series of 8 byte entries of bytes encoding the tuning parameters supported by the system + + + See + + + Used by ibm,get-system-parameter; not supported for + ibm,set-system-parameter. + + + + + 53 + + + Firmware Service Expiration Date + + + This is the date a system's system firmware service warranty + period expires. + + + 8-character null-terminated ASCII string in YYYYMMDD format + + + Used by ibm,get-system-parameter; not supported for + ibm,set-system-parameter. + + + + + 54 + + + Firmware Service Entitlement Activation Key + + + This is the activation key used to set or extend a system's firmware service + warranty period. + + + 34-character null-terminated ASCII string key value + + + Used by ibm,set-system-parameter; not supported for ibm,get-system-parameter + + + + + 55 + + + LPAR Name + + + Logical Partition name + + + Null-terminated ASCII string + + + Used by ibm,set-system-parameter; not supported for ibm,get-system-parameter + + + + + >55 Reserved @@ -24521,193 +24678,378 @@ -
- Universally Unique IDentifier +
+ TLB Block Invalidate Characteristics - The Universally Unique IDentifier (UUID) option provides each - partition with a Universally Unique Identifier that is persisted by the - platform across partition reboots, reconfigurations, OS reinstalls, - partition migration, hibernation etc. The UUID is a 16 byte string of - format fields and random bits as defined in - . The random bits are generated - in an implementation dependent manner to achieve a projected probability - of collision of not greater than one in 2**60. - -
- UUID Format - - - - - - + The Block Invalidate option allows for the removal of multiple page table entries with a single platform wide TLB invalidate + sequence, providing significantly improved performance when removing a virtual memory object. The size of + the block (the number of consecutive virtual memory pages) that is processed by a single TLB invalidate sequence is + implementation dependent. This block size might also be dependent upon the page sizes of the TLB entries. This block + size represents the upper bound of the number of pages that may be processed in a single operation as for example a + single call to H_BLOCK_REMOVE. This system parameter provides the client code the characteristics of the implementation’s + TLB invalidate operations. The TLB Invalidate Characteristics return string is a variable length series of + bytes which contains one or more TLB Block Invalidate Specifiers as defined in Table 108‚ “TLB Block Invalidate + Characteristics Specifier Format‚” on page 253. If the implementation invalidates different sized blocks for different + page size encodings, there will be multiple “TLB Block Invalidate Characteristics Specifiers” within the returned + string. + +
+ TLB Block Invalidate Characteristics Specifier Format + + + + + - - Field - + Byte Offset - - Byte:Bit - + Bit Number in Byte - - - Size (Bits) - - - - - Values - + + Description - + - Version - - - 0:0 + 0 - 1 + 0 - 7 - 0: Initial Version - 1: Reserved + LOG base 2 of the TLB invalidate block size being specified - Random Bits - - - 0:1 thru 5:7 + 1 - 47 + 0 - 7 - Random Bits + Number of page sizes (N) that are supported for the specified TLB invalidate block size - - Generation Method - - - 6:0-3 + + 2 - (N+1) - 4 + 0 - 0b0000 Never Used - 0b0100 Random Generated - All other values are reserved + PTE “L” bit: + 0 = 4K page in a segment who’s base page size is 4K + 1 = page size and segment base size per bits 2 - 7 - Random Bits + 1 - 6:4 - 7:7 + Reserved + + - 12 + 2 - 7 - Random Bits + Encoded segment base page size and actual page size per + Book IVa + + +
+ + + + R1--1. + + For the Block Invalidate option with the + System Parameters option: For the Block Invalidate system + parameter, the ibm,get-system-parameter RTAS call must + never return a Status of -9002 (Not Authorized). + + + + + R1--2. + + For the Block Invalidate option with the + System Parameters option: If the Block Invalidate option + is enabled for the partition, the platform must provide in response + to the ibm,get-system-parameter for + parameter token 50 the one or more TLB Block Invalidate + Specifiers for the calling partition as described in + . + + + + + R1--3. + + For the Block Invalidate option with the + System Parameters option: If the Block Invalidate + option is disabled for the system/partition, the platform must + provide in response to the ibm,get-system-parameter + for parameter token 50 the two byte value 0x0000. + + + + + R1--4. + + For the Block Invalidate option with the + System Parameters option: For the Block Invalidate + system parameter, the ibm,get-system-parameterRTAS call must + always return a Status of -9002 (Setting not allowed/authorized). + + + + +
+ +
+ Energy Management Tuning Parameters (EMTP) + + The energy management tuning parameters are reported. Each parameter occupies + its own 8 byte self-defining entry. As many energy management tuning parameter entries + as are supported by the system are reported, subject to the limitation of the buffer + length. Each reported parameter entry is formatted per + . + + + Format of the Energy Management Tuning Parameter Entry + + + + + + + + + + + + Byte 0 + Byte 1 + Byte 2 + Byte 3 + Byte 4 + Byte 5 + Byte 6 + Byte 7 + + + - Variant + Parameter IdentifierSee + for definition values. - 8:0-1 + Parameter UnitsSee + for definition values. - - 2 + + CurrentParameter Value - - 0b10 DCE Variant UUID - All other values are reserved + + MinimumParameter Value + + + MaximumParameter Value + + +
+ + + Definition of the Energy Management Tuning Parameters + + + + + Parameter ID + Definition + + + + + 0x01 + Utilization threshold for increasing frequency + + + 0x02 + Utilization threshold for decreasing frequency + + + 0x03 + Number of samples for computing utilization statistics + + + 0x04 + Step size for going up in frequency + + + 0x05 + Step size for going down in frequency + + + 0x06 + Delta percentage for determining active cores + + + 0x07 + Utilization threshold to determine active cores with slack + + + 0x08 + Enable/Disable frequency delta between cores + + + 0x09 + Maximum frequency delta between cores + + +   + + + 0x50 + Idle Power Saver enabled/disabled + + + 0x51 + Delay time to enter Idle Power Saver + + + 0x52 + Utilization threshold to enter Idle Power Saver + + + 0x53 + Delay time to exit Idle Power Saver + + + 0x54 + Utilization threshold to exit Idle Power Saver + + +   - Random Bits - - - 8:2 - 15:7 - - - 62 + All other Parameter ID Values are reserved, should calling software + encounter a parameter id value which was reserved at the time it was + written, it shall ignore the specific entry, and only that entry. + + + +
+ + + Definition of the Energy Management Parameter Unit Values + + + + + + Parameter Units + Definition + + + + + 0x00 + Parameter can only be either 1 (enabled) or 0 (disabled) + + + 0x01 + Parameter is time in seconds i.e. 10 = 10 seconds + + + 0x02 + Parameter is a percentage i.e. 10 = 10% + + + 0x03 + Parameter is in 10ths of a percent i.e. 15 = 1.5% + + + 0x04 + Parameter is an integer + + +   - Random Bits + All other Parameter Unit Values are reserved, should calling software + encounter a parameter unit value which was reserved at the time it was + written, it shall ignore the specific entry, and only that entry.
- + - R1-R1--1. - For the UUID option with the System Parameters - option: For the UUID system parameter, the - ibm,get-system-parameter RTAS call must never return - a Status of -9002 (Not Authorized). + For the EMTP option with the System Parameters option: + For the EMTP system parameter, the ibm,get-system-parameter RTAS call + must never return a Status of -9002 (Not Authorized). - R1-R1--2. - For the UUID option with the System Parameters - option: If the UUID option is enabled for the partition, the - platform must provide in response to the - ibm,getsystem-parameter for parameter token 48 the - calling partition unique 16 byte sting as described in - . + For the EMTP option with the System Parameters option: + If the EMTP option is enabled for the partition, the platform must provide in response to the + ibm,get-system-parameter for parameter token 52 the Energy Management + Tuning Parameters for the calling system as described in this section. - R1-R1--3. - For the UUID option with the System Parameters - option: If the UUID option is disabled for the - system/partition, the platform must provide in response to the - ibm,get-system-parameter for parameter token 48 the + For the EMTP option with the System Parameters option: + If the EMTP option is disabled for the system/partition, the platform must provide in + response to the ibm,get-system-parameter for parameter token 52 the two byte value 0x0000. - - R1- + R1--4. - For the UUID option with the System Parameters - option: For the UUID system parameter, the - ibm,set-system-parameter RTAS call must always return - a Status of -9002 (Setting not allowed/authorized). + For the EMTP option with the System Parameters option: + For the EMTP system parameter, the ibm,set-system-parameter RTAS call + must always return a Status of -9002 (Setting not allowed/authorized). - +
- + diff --git a/RTAS/ch_rtas_environment.xml b/RTAS/ch_rtas_environment.xml index aea5dc0..eee5dba 100644 --- a/RTAS/ch_rtas_environment.xml +++ b/RTAS/ch_rtas_environment.xml @@ -1541,7 +1541,7 @@ “ibm,get-indices” - + @@ -1934,7 +1934,7 @@ time and do not change. Information about non-DR dynamic indicators and sensors, needs to be gathered via the ibm,get-indices RTAS call (see - ), and sensors, instead of + ), and sensors, instead of being represented in the device tree. Indicators and sensors within a platform generally have location codes associated with them. Location code information for static diff --git a/RTAS/sec_rtas_get_indices.xml b/RTAS/sec_rtas_get_indices.xml index fdbe42c..2e15cd6 100644 --- a/RTAS/sec_rtas_get_indices.xml +++ b/RTAS/sec_rtas_get_indices.xml @@ -454,7 +454,7 @@
- RTAS Call <emphasis>ibm,set-dynamic-indicator</emphasis> + <emphasis>ibm,set-dynamic-indicator</emphasis> RTAS Call This RTAS call behaves as the RTAS set-indicator call, except that the instance of the @@ -711,7 +711,7 @@
- RTAS Call <emphasis>ibm,get-dynamic-sensor-state</emphasis> + <emphasis>ibm,get-dynamic-sensor-state</emphasis> RTAS Call This RTAS call behaves as the RTAS get-sensor-state call, except that the instance of the sensor is identified by a location code instead of a index. @@ -978,7 +978,7 @@
- RTAS Call <emphasis>ibm,get-vpd</emphasis> + <emphasis>ibm,get-vpd</emphasis> RTAS Call This RTAS call allows for collection of VPD that changes after OS boot time (after the initial reporting in the OF device tree). When this call is implemented, there is no overlap between what is reported in the @@ -1853,7 +1853,7 @@
- RTAS Call <emphasis>ibm,suspend-me</emphasis> + <emphasis>ibm,suspend-me</emphasis> RTAS Call The ibm,suspend-me RTAS call provides the calling OS the ability to suspend processing. Suspension of processing is required as @@ -2504,7 +2504,7 @@
- RTAS Call <emphasis>ibm,update-nodes</emphasis> + <emphasis>ibm,update-nodes</emphasis> RTAS Call This RTAS call is used to determine which device tree nodes have changed due to a massive platform reconfiguration such as when the @@ -2537,13 +2537,13 @@ The opcode of 0x01 is used for deleted nodes -- the operands are the - phandle values for the deleted nodes. + phandle values for the deleted nodes. The opcode of 0x02 is used for updated nodes -- the operands are the - phandle values for the updated nodes. The updated + phandle values for the updated nodes. The updated properties are obtained using the ibm,update-properties RTAS call. @@ -2551,11 +2551,11 @@ The opcode of 0x03 is used for adding nodes -- the operands are pairs of - phandle and - ibm,drc-index values; the - phandle value denotes the parent node of the node to + phandle and + drc-index values; the + phandle value denotes the parent node of the node to be added and the - ibm,drc-index value is passed with the + ibm,drc-index value is passed with the ibm,configure-connector RTAS call to obtain the contents of the added node. @@ -2565,8 +2565,8 @@ (delete) operations (if any) are presented prior to all opcode 0x02 (update) operations (if any), and finally any 0x03 (addition) operations are presented. The - phandle operand values are the same - phandle values as reported by the + phandle operand values are the same + phandle values as reported by the “ibm,phandle” property. @@ -2847,7 +2847,7 @@ The operands for opcode 0x01 in an ibm,update-nodes RTAS call operation list must be the - phandle values for the deleted nodes. + phandle values for the deleted nodes. @@ -2867,7 +2867,7 @@ The operands for opcode 0x02 in an ibm,update-nodes RTAS call operation list must be the - phandle values for the updated nodes that may be used + phandle values for the updated nodes that may be used as the ibm,update-properties RTAS call argument to obtain the changed properties of the updated node. @@ -2890,8 +2890,8 @@ The operands for opcode of 0x03 in an ibm,update-nodes RTAS call operation list must be - phandle and - ibm,drc-index value pairs (each value being 4 bytes + phandle and + drc-index value pairs (each value being 4 bytes on a natural boundary totalling 8 bytes for the pair) denoting the parent node of the added node and the ibm,configure-connector RTAS call argument to obtain @@ -3005,7 +3005,7 @@ - + Negative values: Platform Resource Reassignment events as from event-scan RTAS @@ -3074,7 +3074,17 @@ - + + + ibm,memory-utilization_instrumentation-v# + + + + 0x01-0x03 + + + + 1 Partition Migration / Hibernation @@ -3202,6 +3212,16 @@ 0x01-0x03 + + + + ibm,memory-utilization_instrumentation-v# + + + + 0x01-0x03 + + 2 Activate Firmware @@ -3225,7 +3245,7 @@
- TAS Call <emphasis>ibm,update-properties</emphasis> + <emphasis>ibm,update-properties</emphasis> RTAS Call This RTAS call is used to report updates to the properties changed due to a massive platform reconfiguration such as when the partition is @@ -3251,8 +3271,7 @@ the previous call. A single updated property value string may exceed the capacity of a single 4 K work area. In that case, the updated property value descriptor - for the property appears in the work area of multiple sequential calls to - + for the property appears in the work area of multiple sequential calls to ibm,update-properties RTAS. When the updated property value descriptor contains the final data for the property value, the property string length field of the updated property value descriptor is @@ -3414,7 +3433,7 @@ - phandle of updated node containing updated + phandle of updated node containing updated properties to be reported (4 bytes) @@ -3423,7 +3442,7 @@ 0x00000000 (Indicates Initial call for specified - phandle) + phandle) @@ -3474,7 +3493,7 @@ - phandle of updated node containing updated + phandle of updated node containing updated properties to be reported. @@ -3600,7 +3619,7 @@ - phandle of updated node containing updated + phandle of updated node containing updated properties to be reported (4 Bytes) @@ -3670,7 +3689,7 @@ - + All negative values: Resource Reassignment events as from event-scan RTAS @@ -3678,7 +3697,7 @@ /memory - “ibm,associativity” + “ibm,associativity” @@ -3686,7 +3705,8 @@ ibm,dynamic-reconfiguration-memory - “ibm,dynamic-memory” + “ibm,dynamic-memory” + “ibm,dynamic-memory-v2” @@ -3700,7 +3720,7 @@ - ibm,random-v# + ibm,random-v# @@ -3710,7 +3730,7 @@ - ibm,compression-v# + ibm,compression-v# @@ -3720,7 +3740,7 @@ - ibm,encryption-v# + ibm,encryption-v# @@ -3728,12 +3748,22 @@ - + + + ibm,memory-utilization_instrumentation-v# + + + + <all> + + + + 1 Partition Migration / Hibernation - + - root + root @@ -3792,6 +3822,13 @@ + + + + “ibm,drc-info” + + + @@ -3867,7 +3904,7 @@ - openprom + openprom @@ -3879,7 +3916,7 @@ - rtas + rtas @@ -3950,9 +3987,9 @@ - + - vdevice + vdevice @@ -3961,10 +3998,17 @@ + + + + “ibm,drc-info” + + + children of the - vdevice node + vdevice node @@ -3979,7 +4023,7 @@ - cpu + cpu @@ -4124,14 +4168,14 @@ - "ibm,sub-processors" + “ibm,sub-processors” - cache + cache @@ -4164,14 +4208,14 @@ - l2-cache + l2-cache - options + options @@ -4183,7 +4227,7 @@ - memory + memory @@ -4195,28 +4239,29 @@ - ibm,dynamic-reconfiguration-memory + ibm,dynamic-reconfiguration-memory - “ibm,associativity-lookup-arrays” + “ibm,associativity-lookup-arrays” - “ibm,dynamic-memory” + “ibm,dynamic-memory” + “ibm,dynamic-memory-v2” only the associativity list index fields - “ibm,memory-preservation-time” + “ibm,memory-preservation-time” - /chosen + /chosen @@ -4227,13 +4272,13 @@ - + 1 Partition Migration / Hibernation   - ibm,random-v# + ibm,random-v# @@ -4243,7 +4288,7 @@ - ibm,compression-v# + ibm,compression-v# @@ -4253,7 +4298,17 @@ - ibm,encryption-v# + ibm,encryption-v# + + + + <all> + + + + + + ibm,memory-utilization_instrumentation-v# @@ -4266,7 +4321,7 @@ - rtas + rtas @@ -4306,7 +4361,7 @@
- RTAS call <emphasis>ibm,configure-kernel-dump</emphasis> + <emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call This RTAS call is used to register and unregister with the platform a data structure describing kernel dump information. This dump @@ -5087,6 +5142,11 @@ This RTAS call allows for the discovery of the resources necessary to make a successful subsequent call to ibm,create-dma-window. + + If the ibm,query-pe-dma-window RTAS call is made with Number Outputs + equal to 6, and the “ibm,ddw-extensions” + property does not include list index of 3, + then the call will return a Status of -3 (Invalid Parameter). @@ -5156,7 +5216,9 @@ - 5 + 5 or 6. The value 6 may be used when the ibm,ddw-extensions property + in the PHB node specified by this call indicates support for a 64-bit value of + PE TCEs. See . @@ -5195,7 +5257,7 @@ - + Out @@ -5227,11 +5289,20 @@ - PE TCEs + PE TCEs hi + + + Represents the most-significant 32-bits of the largest contiguous + block of TCEs allocated specifically for (that is, are reserved for) this PE. + + + + + PE TCEs lo - Largest contiguous block of TCEs allocated specifically - for (that is, are reserved for) this PE. See also Requirement + Represents the least-significant 32-bits of the largest contiguous block + of TCEs allocated specifically for (that is, are reserved for) this PE. See also Requirement . @@ -5751,6 +5822,18 @@ bm,reset-pe-dma-windows RTAS Call + + + 2.7 + + + 3 + + + Value of 1 indicates the OS may invoke RTAS ibm,query-pe-dma-window + with Number Outputs equal to 6. Other values are reserved. + + diff --git a/Virtualization/bk_main.xml b/Virtualization/bk_main.xml index c8b35f0..b8daab1 100644 --- a/Virtualization/bk_main.xml +++ b/Virtualization/bk_main.xml @@ -42,7 +42,7 @@ OpenPOWER Foundation - Revision 2.0_pre1 + Revision 2.0_pre2 OpenPOWER @@ -71,6 +71,105 @@ + + 2017-10-11 + + + + Revision 2.0_pre2 - Updates to include latest PAPR ACRs (2.8) as follows: + + + ISA 2.07 privileged doorbell extensions (9/16/2012) + + + POWER ISA Name Change Category Vector.XOR to Vector.CRYPTO (11/4/2012) + + + Enable Multiple Redirected RDMA mappings per page (3/5/2013) + + + Add Block Invalidate Option (3/5/2013) + + + Implementation Dependent Optimizations (3/13/2013) + + + System Firmware Service Entitlement Date (Warranty Date) Check (4/3/2013) + + + New Function for ibm,change-msi to specify 32 bit MSI (5/14/2013) + + + Remove Client-Architecture-Support bit for UUID option (4/16/2013) + + + AddClient Architecture Support bit for RTAS ibm,change-msi (5/28/2013) + + + Add VNIC Server (5/24/2014) + + + VPA changes for P8 (EBB) (5/24/2013) + + + Add an hcall to clean up the entire MMU hashtable (11/20/2013) + + + Add LPCR[ILE] support to H_SET_MODE (5/31/2013) + + + New Root Node Properties (1/12/2016) + + + Extended Firmware Assisted Dump for P8 Registers (1/24/2014) + + + Sufficient H_COP_OP output buffer (6/21/2014) + + + Extend H_SEND_LOGICAL_LAN for large send packets (6/29/2014) + + + Extend H_GET_MPP_X reporting coalesced pages (8/24/2014) + + + Update ibm,pcie-link-speed-stats property to support PCIe 3.0 link speeds (6/12/2015) + + + Extend ibm,get-system-parameters RTAS to report Energy Management Tuning Parameters (3/18/2015) + + + Additional System Parameters related to mgmt of FW Service Entitlement Warranty period (6/22/2015) + + + Additional System Parameter to read LPAR Name string (10/7/2015) + + + Redesign of properties for DRC information and dynamic memory (7/23/2015) + + + Add additional logical loction code sections (3/4/2016) + + + Add ibm,vnic-client-mac to support vNIC failover (2/29/2016) + + + hcall for registering the process table (3/21/2016) + + + New device tree property for UUID (3/21/2016) + + + Changes for Hotplug RTAS Events (10/24/2016) + + + Support 64-bit PE TCEs in ibm,query-pe-dma-window (7/14/2016) + + + + + + 2017-05-18 diff --git a/Virtualization/ch_dynamic_reconfig.xml b/Virtualization/ch_dynamic_reconfig.xml index 6f950f0..1361f22 100644 --- a/Virtualization/ch_dynamic_reconfig.xml +++ b/Virtualization/ch_dynamic_reconfig.xml @@ -1122,14 +1122,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Property - <emphasis role="bold"><literal>“ibm,drc-indexes”</literal></emphasis> + <emphasis role="bold"><literal>“ibm,drc-indexes”</literal></emphasis> Property This property is added for the DR option to specify for each DR connector an index to be passed between the OS and RTAS to identify the DR connector to be operated upon. This property is in the parent node of the DR connector to which the property applies. See for the definition of this - property. + property. See for additional information. @@ -1146,8 +1145,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Property - <emphasis role="bold"><literal>“ibm,my-drc-index”</literal></emphasis> + <emphasis role="bold"><literal>“ibm,my-drc-index”</literal></emphasis> Property This property is added for the DR option to specify for each node which has a DR connector between it and its parent, the value of the entry in the @@ -1171,12 +1169,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Property - <emphasis role="bold"><literal>“ibm,drc-names”</literal></emphasis> + <emphasis role="bold"><literal>“ibm,drc-names”</literal></emphasis> Property This property is added for the DR option to specify for each DR connector a user-readable location code for the connector. See for the definition of this - property. + property. See for additional information. @@ -1287,7 +1284,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> This property is added for the DR option to specify for each DR connector the power domain in which the connector resides. See for the definition of this - property. + property. See for additional information. @@ -1323,12 +1320,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Property - <emphasis role="bold"><literal>“ibm,drc-types”</literal></emphasis> + <emphasis role="bold"><literal>“ibm,drc-types”</literal></emphasis> Property This property is added for the DR option to specify for each DR connector a user-readable connector type for the connector. See for the definition of this - property. + property. See for additional information. Architecture Note: The logical connectors (CPU, MEM etc.) represent DR boundaries that may not have physical DR connectors @@ -1354,8 +1350,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- Property - <emphasis role="bold"><literal>“ibm,phandle”</literal></emphasis> + <emphasis role="bold"><literal>“ibm,phandle”</literal></emphasis> Property This property is added for the DR option to specify the phandle for each OF device tree node returned by ibm,configure-connector. See for the definition of this @@ -1377,6 +1372,57 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
+ +
+ <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. + When present, it replaces those properties. + + + + R1--1. + + 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--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 + “ibm,drc-power-domains” will be present. + + + + + 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” + set of properties. The property or properties presented will based on the capability of the target partition. + + + + +
@@ -1416,7 +1462,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> 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 - “ibm,drc-power-domains” property). The + “ibm,drc-indexes” or + “ibm,drc-info” property). The input is the power domain and the output is the power level that is actually to be set for that domain; for purposes of DR, only two of the current power levels are of interest: “full on” and @@ -1769,7 +1816,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> get-sensor-state RTAS call for the sensors in must be the index for the connector, as passed in the - “ibm,drc-indexes” property. + “ibm,drc-indexes” or + “ibm,drc-info” property. Hardware and Software Implementation Note: The status introduced in Requirement @@ -1997,7 +2045,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> set-indicator RTAS call for the indicators in must be the index for the connector, as passed in the - “ibm,drc-indexes” property. + “ibm,drc-indexes” or + “ibm,drc-info” property. @@ -2269,7 +2318,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> entry from the - “ibm,drc-indexes” property for + “ibm,drc-indexes” or + “ibm,drc-info” property for the connector to configure @@ -2325,10 +2375,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> which returns “configuration complete” status. A subsequent sequence of calls to ibm,configure-connector with the same entry from the - “ibm,drc-indexes” property will restart + “ibm,drc-indexes” or + “ibm,drc-info” property will restart the configuration of devices which were not completely configured. If the index from - “ibm,drc-indexes” refers to a connector + “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 ibm,configure-connector RTAS call for that index @@ -3670,6 +3722,17 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> . + + + + “ibm,drc-info” + + + + As defined in + . + + @@ -3690,14 +3753,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> xrefstyle="select: labelnumber nopage"/>-2. For the LRDR option: The - /cpus OF device tree node must include - “ibm,drc-types” (of type CPU), - “ibm,drc-power-domains” - (of value -1), - “ibm,drc-names”, and - “ibm,drc-indexes” - properties with entries for each potentially - supported dynamically reconfigurable processor. + /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 properties must contain entries for each potentially supported dynamically reconfigurable processor. @@ -3707,14 +3771,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> For the LRDR option: The root node of the OF device tree must include - “ibm,drc-types” - (of type MEM), - “ibm,drc-power-domains” - (of value -1), - “ibm,drc-names”, and - “ibm,drc-indexes” - properties with entries for each potentially - supported dynamically reconfigurable memory region. + 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 + reconfigurable memory region. @@ -3735,14 +3800,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> For the LRDR option: The root node of the OF device tree must include - “ibm,drc-types” - (of type PHB), - “ibm,drc-power-domains” - (of value -1), - “ibm,drc-names”, and - “ibm,drc-indexes” - properties with entries for each potentially - supported dynamically reconfigurable PHB. + 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. @@ -3753,14 +3819,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> For the LRDR option: The /pci OF device tree node representing a PHB must include - “ibm,drc-types” - (of type SLOT), - “ibm,drc-power-domains” - (of value -1), - “ibm,drc-names”, and - “ibm,drc-indexes” - properties with entries for each potentially - supported dynamically reconfigurable PCI SLOT. + 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. diff --git a/Virtualization/ch_lpar_option.xml b/Virtualization/ch_lpar_option.xml index 019471f..3f8dafb 100644 --- a/Virtualization/ch_lpar_option.xml +++ b/Virtualization/ch_lpar_option.xml @@ -531,8 +531,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo dependent interfaces do not appear in this document. - Architected hcall()s - <emphasis>(Continued)</emphasis> + Architected hcall()s @@ -573,6 +572,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Page Frame Table + + + + / + + + + Removes PTEs of a naturally aligned block of Virtual addresses from the partition’s Page Frame Table + + @@ -716,6 +725,26 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Manage the Extended DABR facility. + + + + / + + + + Adjust implementation dependent tuning values + + + + + + / + + + + Set implementation dependent tuning switches + + @@ -803,6 +832,16 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo maintenance. + + + + / + + + + Clears the hash page table for a partition in preparation for a restart + + @@ -1470,6 +1509,76 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo range + + + + / + + + + Configure Memory Usage Instrumentation + + + + + + / + + + + Reset page age and affinity log, and/or PUT/HBA + + + + + + / + + + + Return the page usage information for a logical address range of pages + + + + + + / + + + + Return multiple HBA + + + + + + / + + + + Invalidate the specified process segment from all segment lookaside buffers in the system. + + + + + + / + + + + Invalidate the specified process table entry. + + + + + + / + + + + Manage the virtual address translation mode including registration of a process table. + +
@@ -3645,1570 +3754,1836 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - Reserved for platform-dependent hcall()s / - + + / + - 0xF000 - 0xFFFC + 0x328 -   + Critical -   + if the platform supports the "block invalidate" option -   + hcall-block-remove - ILLEGAL + + / + - Any token value having a one in either of the low order - two bits + 0x32C -   + normal -   + If the Memory Usage Instrumentation Option is implemented -   + hcall-mui - Reserved + + / + - 0x328 - 0xEFFC and 0x10000 - 0xFFFFFFFF-FFFFFFFC: RTAS - implementations may assigns values in these ranges to their own - internal interfaces, as long as they are prepared for the - growth of architected functions into this range. + 0x330 -   + normal -   + If the Memory Usage Instrumentation Option is implemented -   + hcall-mui - - - - Firmware Implementation Note: The assignment of function tokens is - designed such that a single mask operation can validate that the value is - within the range of a reasonable size branch table. Entries within the - branch table can handle unimplemented code points. - The hypervisor routines are optimized for execution speed. In some - rare cases, locks are taken, and specific hardware designs require short - wait loops. However, if a needed resource is truly busy, or processing is - required by an agent, the hypervisor returns to the caller, either to - have the function retried or continued at a later time. The Performance - Class establishes specific performance requirements against each specific - hcall() function as defined below. - Hypervisor Call Performance Classes: - Critical Must make continuous forward progress, encountering any - busy resource must cause the function to back out and return with a - “hardware busy” return code. When subsequently called, the - operation begins again. Short loops for larwx and stwcx to acquire an - apparently unheld lock are allowed. These functions may not include wait - loops for slow hardware access. - Normal Similar to critical, however, wait loops for slow hardware - access are allowed. These functions may not include wait loops for an - agent such as an external micro-processor or message transmission - device. - Continued This class of functions is expected to serialize on the - use of external agents. If the external agent is busy the function - returns “hardware busy”. If the interface to the external - agent is not busy, the interface is marked busy and used to start the - function. The function returns one of the “function in - progress” return codes. Later, the caller may check on the - completion of the function by issuing the “check” Hcall - function with the “function in progress” parameter code. If - the function completed properly, the hypervisor maintains no status and - the “check” Hcall returns success. If the operation is still - in process, the same “function in progress” code is returned. - If the function completed in error, the completion error code is - returned. The hypervisor maintains room for at least one outstanding - error status per external agent interface per processor. If there is no - room to record the error status, the hypervisor returns “hardware - busy” and does not start the function. - Terminal This class of functions is used to manage a partition when - the OS is not in regular operation. These events include postmortems and - extensive recoveries. - The hypervisor performance classes are ordered in decreasing - restriction. - - - - R1--3. - - For the LPAR option: The caller must perform properly - given that the hypervisor meets the performance class specified. - - - - - R1--4. - - For the LPAR option: The hypervisor implementation - must meet the specified performance class or higher. - - - - - R1--5. - - For the LPAR option: Platform hardware designs must - take the allowable performance classes into account when choosing the - hardware access technology for the various facilities. - - - - - R1--6. - - For the LPAR option: The hypervisor must have the - capability to receive and handle the hypervisor call interrupts - simultaneously on multiple processors in the same or different partitions - up to the number of processors in the system. - - - - - R1--7. - - For the LPAR option: The hypervisor must check the - state of the MSR register bits that are not set to a specific value by - the processor hardware during the invoking interrupt per - . - - - - - - MSR State on Entrance to Hypervisor - - - - - - - MSR Bit - - - - - Required State + / - - Error-Code - + 0x334 - - - - - HV - Hypervisor + normal - 1 + If the Memory Usage Instrumentation Option is implemented - None + hcall-mui - Bits 2,4:46, 57, and 60 Reserved - - - Set to 0 by Hardware + + / + - None + 0x338 - - - ILE - Interrupt Little Endian + normal - As Last set by the hypervisor + If the Memory Usage Instrumentation Option is implemented - None + hcall-mui - ME - Machine check Enable + + / + - As last set by the hypervisor - - - None + 0x33C - - - LE Little-Endian Mode + Normal - 0 forced by ILE + If the plaform implements the LRDR option at LoPAR Verstion 2.8 or higher - None + hcall-implementation-dependent-tuning - - -
- - - - R1--8. - - For the LPAR option: The Hcall() flags field must - meet the definition in: - ; the hypervisor may safely - ignore flag field values not explicitly defined by the specific hcall() - semantic. - - - - - R1--9. - - For the LPAR option: The platform must ensure that - flag field values not defined for a specific hcall() do not compromise - partitioning integrity. - - - - - R1--10. - - For the LPAR option: Implementations that normally - choose to ignore invalid flag field values must provide a “debug - mode” that does check for invalid flag field values and returns - H_Parameter when any are found. - - Architecture Note: The method for invocation of a - platform’s “debug mode” is beyond the scope of this - architecture. - - - - - - Page Frame Table Access flags field - definition - - - - - - - - - - - Bit - - - - - Function - - - - - Bit - - - - - Function + / - - Bit - + 0x340 - - Function - + Normal - - Bit - + If the plaform implements the LRDR option at LoPAR Verstion 2.8 or higher - - Function - + hcall-implementation-dependent-tuning - - - - 0-15 - - - NUMA CEC Cookie - - - 16-23 - - - Subfunction Codes + + Reserved - 32 + 0x344-0x354 - AVPN +   - 48 +   - Zero Page +   - 33 + + / + - andcond + 0x358 - 49 + Terminal - Copy Page + For LoPAR Verstion 2.8 and higher + + + hcall-clr-hpt - - 34-39 - - + Reserved - 50-54 + 0x35C-0x370 - key0-key4 - Bits 50-54 (key0 - key4) shall be treated as reserved - on platforms that either do not contain an - “ibm,processor-storage-keys” property, - or contain an - “ibm,processor-storage-keys” property - with the value of zero in both cells. - +   - - - 55 +   - pp0 - Bit 55 (pp0) shall be treated as reserved on platforms - that do not have the “Support for the “110” - value of the Page Protection (PP) bits” bit set to a - value of 1 in the - “ibm,pa-features” property. - +   - 24 - - - Exact + + / + - 40 + 0x374 - I-Cache-Invalidate + Normal - 56 + If the platform supports the In-Memory Table Translation Option - Compression + hcall-imtt - 25 - - - R-XLATE + + / + - 41 + 0x378 - I-Cache-Synchronize + Normal - 57 + If the platform supports the In-Memory Table Translation Option - Checksum + hcall-imtt - 26 + + / + - READ-4 + 0x37C - 42 + Normal - CC (Coalesce Candidate) - - - 58-60 + If the platform supports the In-Memory Table Translation Option - - Reserved + + hcall-imtt - 27 + Reserved for platform-dependent hcall()s / + - Reserved + 0xF000 - 0xFFFC - - 43-47 + +   - - Reserved + +   + + +   - - 28-31 + + ILLEGAL - - CMO Option Flags + + Any token value having a one in either of the low order + two bits - - - 61 +   - N +   + + +   - 62 + Reserved - pp1 + 0x380 - 0xEFFC and 0x10000 - 0xFFFFFFFF-FFFFFFFC: RTAS + implementations may assigns values in these ranges to their own + internal interfaces, as long as they are prepared for the + growth of architected functions into this range. - - - 63 +   - pp2 +   + + +  
- - - - R1--11. - - For the LPAR option: The caller of Hcall must be in - privileged mode (MSRPR = 0) or the hypervisor immediately returns an - H_Privilege return code. See - for this and other architected - return codes. - - - - - R1--12. - - For the LPAR option: The caller of hcall() must be - prepared for a return code of H_Hardware from all functions. - - - - + Firmware Implementation Note: The assignment of function tokens is + designed such that a single mask operation can validate that the value is + within the range of a reasonable size branch table. Entries within the + branch table can handle unimplemented code points. + The hypervisor routines are optimized for execution speed. In some + rare cases, locks are taken, and specific hardware designs require short + wait loops. However, if a needed resource is truly busy, or processing is + required by an agent, the hypervisor returns to the caller, either to + have the function retried or continued at a later time. The Performance + Class establishes specific performance requirements against each specific + hcall() function as defined below. + Hypervisor Call Performance Classes: + Critical Must make continuous forward progress, encountering any + busy resource must cause the function to back out and return with a + “hardware busy” return code. When subsequently called, the + operation begins again. Short loops for larwx and stwcx to acquire an + apparently unheld lock are allowed. These functions may not include wait + loops for slow hardware access. + Normal Similar to critical, however, wait loops for slow hardware + access are allowed. These functions may not include wait loops for an + agent such as an external micro-processor or message transmission + device. + Continued This class of functions is expected to serialize on the + use of external agents. If the external agent is busy the function + returns “hardware busy”. If the interface to the external + agent is not busy, the interface is marked busy and used to start the + function. The function returns one of the “function in + progress” return codes. Later, the caller may check on the + completion of the function by issuing the “check” Hcall + function with the “function in progress” parameter code. If + the function completed properly, the hypervisor maintains no status and + the “check” Hcall returns success. If the operation is still + in process, the same “function in progress” code is returned. + If the function completed in error, the completion error code is + returned. The hypervisor maintains room for at least one outstanding + error status per external agent interface per processor. If there is no + room to record the error status, the hypervisor returns “hardware + busy” and does not start the function. + Terminal This class of functions is used to manage a partition when + the OS is not in regular operation. These events include postmortems and + extensive recoveries. + The hypervisor performance classes are ordered in decreasing + restriction. + + + R1--13. + xrefstyle="select: labelnumber nopage"/>-3. - For the LPAR option: - In order for the platform to return H_Hardware, the error must not have resulted in an - undetectable state/data corruption nor will continued operation propagate - an undetectable state/data corruption as a result of the original - error. - Notes: - - - A detectable corruption, when accessed, results in either a - H_Hardware return code, machine check or check stop per platform - policy. - - - - Among other implications of Requirement - are: the effective state of the - partition appears to not change due to the failed hcall() -- (any partial - changes to persistent state/data are backed out); and the recovery of - platform resources that held lost state/data does not hide the state/data - loss to subsequent users of that state/data. - - - - The operating system is not expected to log a serviceable event - due to an H_Hardware return code from an hcall(), and treats the hcall() - as failing due to nonspecific hardware reasons. Any logging of a - serviceable event in response to the underlying cause is handled by - separate platform initiated operations. - - - + For the LPAR option: The caller must perform properly + given that the hypervisor meets the performance class specified. + + + + + R1--4. + + For the LPAR option: The hypervisor implementation + must meet the specified performance class or higher. + + + + + R1--5. + + For the LPAR option: Platform hardware designs must + take the allowable performance classes into account when choosing the + hardware access technology for the various facilities. + + + + + R1--6. + + For the LPAR option: The hypervisor must have the + capability to receive and handle the hypervisor call interrupts + simultaneously on multiple processors in the same or different partitions + up to the number of processors in the system. + + + + + R1--7. + + For the LPAR option: The hypervisor must check the + state of the MSR register bits that are not set to a specific value by + the processor hardware during the invoking interrupt per + . - - Hypervisor Call Return Code Table - - - - +
+ MSR State on Entrance to Hypervisor + + + + + - Hypervisor Call Return Code Values - (R3) + MSR Bit - + - Meaning + Required State - - - - - - 0x0100000 - 0x0FFFFFFF - - - Function in Progress - - - - - 9905 - - - H_LongBusyOrder100sec - Similar to LongBusyOrder1msec, - but the hint is 100 second wait this time. - - - - - 9904 - - - H_LongBusyOrder10sec - Similar to LongBusyOrder1msec, but - the hint is 10 second wait this time. - - - - - 9903 - - H_LongBusyOrder1Sec - Similar to LongBusyOrder1msec, but - the hint is 1 second wait this time. - - - - - 9902 - - - H_LongBusyOrder100mSec - Similar to LongBusyOrder1msec, - but the hint is 100mSec wait this time. + + Error-Code + + + - 9901 - - - H_LongBusyOrder10mSec - Similar to LongBusyOrder1msec, - but the hint is 10mSec wait this time. + HV - Hypervisor - - - 9900 + 1 - H_LongBusyOrder1msec - This return code is identical to - H_Busy, but with the added bonus of a hint to the partition OS. - If the partition OS can delay for 1 millisecond, the hcall will - likely succeed on a new hcall with no further busy return - codes. If the partition OS cannot handle a delay, they are - certainly free to immediately turn around and try again. + None - 18 - - - H_CONTINUE + Bits 2,4:46, 57, and 60 Reserved - - - 17 + Set to 0 by Hardware - H_PENDING + None - 16 - - - H_PARTIAL_STORE + ILE - Interrupt Little Endian - - - 15 + As Last set by the hypervisor - H_PAGE_REGISTERED + None - 14 - - - H_IN_PROGRESS + ME - Machine check Enable - - - 13 + As last set by the hypervisor - Sensor value >= Critical high + None - 12 - - - Sensor value >= Warning high + LE Little-Endian Mode - - - 11 + 0 forced by ILE - Sensor value normal - - - - - 10 - - - Sensor value <= Warning low + None + + +
+ + + + R1--8. + + For the LPAR option: The Hcall() flags field must + meet the definition in: + ; the hypervisor may safely + ignore flag field values not explicitly defined by the specific hcall() + semantic. + + + + + R1--9. + + For the LPAR option: The platform must ensure that + flag field values not defined for a specific hcall() do not compromise + partitioning integrity. + + + + + R1--10. + + For the LPAR option: Implementations that normally + choose to ignore invalid flag field values must provide a “debug + mode” that does check for invalid flag field values and returns + H_Parameter when any are found. + + Architecture Note: The method for invocation of a + platform’s “debug mode” is beyond the scope of this + architecture. + + + + + + Page Frame Table Access flags field + definition + + + + + + + + + + - 9 + + Bit + - Sensor value <= Critical low + + Function + - - - 5 + + Bit + - H_PARTIAL (The request completed only partially - successful. Parameters were valid but some specific hcall - function condition prevented fully completing the architected - function, see the specific hcall definition for possible - reasons.) + + Function + - - - 4 + + Bit + - H_Constrained (The request called for resources in excess - of the maximum allowed. The resultant allocation was - constrained to maximum allowed) + + Function + - - - 3 + + Bit + - H_NOT_AVAILABLE + + Function + + + + + 0-15 + + + NUMA CEC Cookie + + + 16-23 + + + Subfunction Codes + - 2 + 32 - H_Closed (virtual I/O connection is closed) + AVPN - - - 1 + 48 - H_Busy - Hardware Busy -- Retry Later + Zero Page - 0 + 33 - H_Success + andcond - - - -1 + 49 - H_Hardware (Error) + Copy Page + + 34-39 + + + Reserved + - -2 + 50-54 - H_Function (Not Supported) + key0-key4 + Bits 50-54 (key0 - key4) shall be treated as reserved + on platforms that either do not contain an + “ibm,processor-storage-keys” property, + or contain an + “ibm,processor-storage-keys” property + with the value of zero in both cells. + - -3 + 55 - H_Privilege (Caller not in privileged mode). + pp0 + Bit 55 (pp0) shall be treated as reserved on platforms + that do not have the “Support for the “110” + value of the Page Protection (PP) bits” bit set to a + value of 1 in the + “ibm,pa-features” property. + - -4 + 24 - H_Parameter (Outside Valid Range for Partition or - conflicting) + Exact - - - -5 + 40 - bad_mode (Illegal MSR value) + I-Cache-Invalidate - - - -6 + 56 - H_PTEG_FULL (The requested pteg was full) + Compression - -7 + 25 - H_Not_Found (The requested entity was not found) + R-XLATE - - - -8 + 41 - H_RESERVED_DABR (The requested address is reserved by the - hypervisor on this processor) + I-Cache-Synchronize - - - -9 + 57 - H_NOMEM + Checksum - -10 + 26 - H_AUTHORITY (The caller did not have authority to perform - the function) + READ-4 - - - -11 + 42 - H_Permission (The mapping specified by the request does - not allow for the requested transfer) + CC (Coalesce Candidate) + + + 58-60 + + + Reserved - -12 + 27 - H_Dropped (One or more packets could not be delivered to - their requested destinations) + Reserved + + + 43-46 + + + MUI Options + Bits 43-46 (MUI Options) detail is provided in + + in . + - - -13 + + 28-31 - - H_S_Parm (The source parameter is illegal) + + CMO Option Flags - -14 + 61 - H_D_Parm (The destination parameter is illegal) + N - -15 + 62 - H_R_Parm (The remote TCE mapping is illegal) + pp1 - -16 + 47 - H_Resource (One or more required resources are in - use) + Reserved - - - -17 + 63 - H_ADAPTER_PARM (invalid adapter) + pp2 - + + +
+ + + + R1--11. + + For the LPAR option: The caller of Hcall must be in + privileged mode (MSRPR = 0) or the hypervisor immediately returns an + H_Privilege return code. See + for this and other architected + return codes. + + + + + R1--12. + + For the LPAR option: The caller of hcall() must be + prepared for a return code of H_Hardware from all functions. + + + + + R1--13. + + For the LPAR option: + In order for the platform to return H_Hardware, the error must not have resulted in an + undetectable state/data corruption nor will continued operation propagate + an undetectable state/data corruption as a result of the original + error. + Notes: + + + A detectable corruption, when accessed, results in either a + H_Hardware return code, machine check or check stop per platform + policy. + + + + Among other implications of Requirement + are: the effective state of the + partition appears to not change due to the failed hcall() -- (any partial + changes to persistent state/data are backed out); and the recovery of + platform resources that held lost state/data does not hide the state/data + loss to subsequent users of that state/data. + + + + The operating system is not expected to log a serviceable event + due to an H_Hardware return code from an hcall(), and treats the hcall() + as failing due to nonspecific hardware reasons. Any logging of a + serviceable event in response to the underlying cause is handled by + separate platform initiated operations. + + + + + + + + + Hypervisor Call Return Code Table + + + + + + - -18 + + Hypervisor Call Return Code Values + (R3) + - - H_RH_PARM (resource not valid or logical partition - conflicting) + + + Meaning + + + - -19 + 0x0100000 - 0x0FFFFFFF - H_RCQ_PARM (RCQ not valid or logical partition - conflicting) + Function in Progress - -20 + 9905 - H_SCQ_PARM (SCQ not valid or logical partition - conflicting) + H_LongBusyOrder100sec - Similar to LongBusyOrder1msec, + but the hint is 100 second wait this time. - -21 + 9904 - H_EQ_PARM (EQ not valid or logical partition - conflicting) + H_LongBusyOrder10sec - Similar to LongBusyOrder1msec, but + the hint is 10 second wait this time. - -22 + 9903 - H_RT_PARM (invalid resource type) + H_LongBusyOrder1Sec - Similar to LongBusyOrder1msec, but + the hint is 1 second wait this time. - -23 + 9902 - H_ST_PARM (invalid service type) + H_LongBusyOrder100mSec - Similar to LongBusyOrder1msec, + but the hint is 100mSec wait this time. - -24 + 9901 - H_SIGT_PARM (invalid signalling type) + H_LongBusyOrder10mSec - Similar to LongBusyOrder1msec, + but the hint is 10mSec wait this time. - -25 + 9900 - H_TOKEN_PARM (invalid token) + H_LongBusyOrder1msec - This return code is identical to + H_Busy, but with the added bonus of a hint to the partition OS. + If the partition OS can delay for 1 millisecond, the hcall will + likely succeed on a new hcall with no further busy return + codes. If the partition OS cannot handle a delay, they are + certainly free to immediately turn around and try again. - -27 + 18 - H_MLENGTH_PARM (invalid memory length) + H_CONTINUE - -28 + 17 - H_MEM_PARM (invalid memory I/O virtual address) + H_PENDING - -29 + 16 - H_MEM_ACCESS_PARM (invalid memory access control) + H_PARTIAL_STORE - -30 + 15 - H_ATTR_PARM (invalid attribute value) + H_PAGE_REGISTERED - -31 + 14 - H_PORT_PARM (invalid port number) + H_IN_PROGRESS - -32 + 13 - H_MCG_PARM (invalid multicast group) + Sensor value >= Critical high - -33 + 12 - H_VL_PARM (invalid virtual lane) + Sensor value >= Warning high - -34 + 11 - H_TSIZE_PARM (invalid trace size) + Sensor value normal - -35 + 10 - H_TRACE_PARM (invalid trace buffer) + Sensor value <= Warning low - -36 + 9 - H_TRACE_PARM (invalid trace buffer) + Sensor value <= Critical low - -37 + 5 - H_MASK_PARM (invalid mask value) + H_PARTIAL (The request completed only partially + successful. Parameters were valid but some specific hcall + function condition prevented fully completing the architected + function, see the specific hcall definition for possible + reasons.) - -38 + 4 - H_MCG_FULL (multicast attachments exceeded) + H_Constrained (The request called for resources in excess + of the maximum allowed. The resultant allocation was + constrained to maximum allowed) - -39 + 3 - H_ALIAS_EXIST (alias QP already defined) + H_NOT_AVAILABLE - -40 + 2 - H_P_COUNTER (invalid counter specification) + H_Closed (virtual I/O connection is closed) - -41 + 1 - H_TABLE_FULL (resource page table full) + H_Busy + Hardware Busy -- Retry Later - -42 + 0 - H_ALT_TABLE (alternate table already exists / alternate - page table not available) + H_Success - -43 + -1 - H_MR_CONDITION (invalid memory region condition) + H_Hardware (Error) - -44 + -2 - H_NOT_ENOUGH_RESOURCES (insufficient resources) + H_Function (Not Supported) - -45 + -3 - H_R_STATE (invalid resource state condition or sequencing - error) + H_Privilege (Caller not in privileged mode). - -46 + -4 - H_RESCINDED + H_Parameter (Outside Valid Range for Partition or + conflicting) - -54 + -5 - H_Aborted + bad_mode (Illegal MSR value) - -55 + -6 - H_P2 + H_PTEG_FULL (The requested pteg was full) - -56 + -7 - H_P3 + H_Not_Found (The requested entity was not found) - -57 + -8 - H_P4 + H_RESERVED_DABR (The requested address is reserved by the + hypervisor on this processor) - -58 + -9 - H_P5 + H_NOMEM - -59 + -10 - H_P6 + H_AUTHORITY (The caller did not have authority to perform + the function) - -60 + -11 - H_P7 + H_Permission (The mapping specified by the request does + not allow for the requested transfer) - -61 + -12 - H_P8 + H_Dropped (One or more packets could not be delivered to + their requested destinations) - -62 + -13 - H_P9 + H_S_Parm (The source parameter is illegal) - -63 + -14 - H_NOOP + H_D_Parm (The destination parameter is illegal) - -64 + -15 - H_TOO_BIG + H_R_Parm (The remote TCE mapping is illegal) - -65 + -16 - Reserved + H_Resource (One or more required resources are in + use) - -66 + -17 - Reserved + H_ADAPTER_PARM (invalid adapter) - -67 + -18 - H_UNSUPPORTED (Parameter value outside of the range - supported by this implementation) + H_RH_PARM (resource not valid or logical partition + conflicting) - -68 + -19 - H_OVERLAP (unsupported overlap among passed buffer - areas) + H_RCQ_PARM (RCQ not valid or logical partition + conflicting) - -69 + -20 - H_INTERRUPT (Interrupt specification is invalid) + H_SCQ_PARM (SCQ not valid or logical partition + conflicting) - -70 + -21 - H_BAD_DATA (uncorrectable data error) + H_EQ_PARM (EQ not valid or logical partition + conflicting) - -71 + -22 - H_NOT_ACTIVE (Not associated with an active - operation) + H_RT_PARM (invalid resource type) - -72 + -23 - H_SG_LIST (A scatter/gather list element is - invalid) + H_ST_PARM (invalid service type) - -73 + -24 - H_OP_MODE (There is a conflict between - the subcommand and the requested operation - notification) + H_SIGT_PARM (invalid signalling type) - -74 + -25 - H_COP_HW (co-processor hardware error) + H_TOKEN_PARM (invalid token) - -75 + -27 - H_STATE (invalid state) + H_MLENGTH_PARM (invalid memory length) - -76 + -28 - H_RESERVED (a reserved value was specified) + H_MEM_PARM (invalid memory I/O virtual address) - -77 : -255 + -29 - Reserved + H_MEM_ACCESS_PARM (invalid memory access control) - -256 -- -511 + -30 - H_UNSUPPORTED_FLAG (An unsupported binary flag bit was - specified. The returned value is -256 - the bit position of the - unsupported flag bit [high order flag bit is 0 etc.]) + H_ATTR_PARM (invalid attribute value) - - -
-
- -
- Hypervisor Call Functions - - -
- Page Frame Table Access - All hypervisor Page Frame Table (PFT) access routines are called - using 64 bit linkage conventions and apply to all page sizes that the - platform supports as specified by the - “ibm,processor-page-sizes” property (See - for more details). The hypervisor PFT - access functions carefully update a given Page Table Entry (PTE) with at - least 64 bit store operations since an invalid update sequence could - result in machine checks. To guard against multiple conflicting - allocations of a PTE that could result in a check stop condition, the - hypervisor PTE allocation routine (H_ENTER) reserves the first two (high - order) software PTE bits for use as PTE locks while the low order two - software PTE bits are reserved for OS use (not used by firmware). If a - firmware PTE bit is on, the OS is to assume that the PTE is in use, just - as if the V bit were on. The hypervisor PFT access routines often execute - the tlbie instruction, on certain platforms, this instruction may only be - executed by one processor in a partition at a time, the hypervisor uses - locks to assure this. The tlbie instruction flushes a specific translate - lookaside buffer (TLB) entry from all processors participating in the - protocol. All the processors participating in the tlbie protocol are - defined as a translation domain. All processors of a given partition that - are in a given translation domain share the same hardware PFT. Book III - of the PA specifies the codes sequences needed to safely access the PFT, - in its chapter titled “Storage Control Instructions and Table - Updates”. These code sequences are part of this specification by - reference. The hypervisor PFT access routines are in the critical - performance path of the machine, therefore, extraordinary care must be - given to their performance, including machine dependent coding, minimal - run time checking, and code path length optimization. For performance - reasons, all parameter linkage is through registers, and no indirect - parameter linkage is allowed. This requires special glue code on the part - of the caller to pick up the return parameters. The hypervisor PFT access - routines modify the calling processor’s partition PFT on the - calling node. On NUMA systems, if an LPAR partition spans multiple - Central Electronics Complexes (CECs), the partition’s processors - may be in separate translation domains. Each platform translation domain - has a separate PFT. Therefore, the partition’s OS must modify each - PFT individually. This is done either by making hcall() accesses - specifying the NUMA CEC Cookie (which identifies the translation domain) - in the high order 16 bits of the flags parameter (H_ENTER and H_READ - only) or by issuing the hcall() from a processor within the translation - domain as identified by the processor’s NUMA CEC Cookie field of - the - “ibm,pft-size” property. - The PFT is preallocated based upon the value of the - partition’s PFT_size configuration variable. This configuration - variable is initialized to 4 PTEs per node local page frame and 2 PTEs - per remote node page frame. The size of the PFT per node is communicated - to the partition’s OS image via the - “ibm,pft-size” property of the - node. - The value of the configuration variable - PFT_size consists of two comma separated integers, - the first is the number of hardware PFT entries to allocate per CEC local - page, and the second is the number of hardware PFT entries to allocate - per remote CEC page (if NUMA configured). These allocations are made at - partition boot time based upon the initial partition memory allocation, - based upon specific situations (such as low page table usage or future - need for dynamic memory addition) the OS may wish to override the - platform default values. - - - - R1--1. - - For the LPAR option: The platform must allocate the - partition’s page frame table. The size of this table is determined - by the PFT_size configuration variable in the OS image’s - “common” NVRAM partition. - - - - - R1--2. - - For the LPAR option: The platform must provide the - “ibm,pft-size” property in the processor - nodes of the device tree (children of type - cpu of the - /cpus node). - Register Linkage (For hcall() tokens 0x04 - 0x18) - - - - - - On Call: - - R3 function call token - R4 flags (see ) - R5 Page Table Entry Index (PTEX) - R6 Page Table Entry High word (PTEH) (on H_ENTER only) - R7 Page Table Entry Low word (PTEL) (on H_ENTER only) - - - On Return: - - R3 Status Word - R4 chosen PTEX (from H_ENTER) / High Order Half of old PTE - R5 Low Order Half of old PTE - R6 - - - - - Semantics checks for all hypervisor PTE access routines: - - - - Hypervisor checks that the caller was in privileged mode or - H_Privilege return code. - - - - On NUMA platforms for the H_ENTER and H_READ calls only, the - hypervisor checks that the NUMA CEC Cookie is within the range of values - assigned to the partition else return H_Parameter. - - - - Hypervisor checks that the PTEX is zero or greater and less than - the partition maximum, else H_Parameter return code. - - - - Hypervisor checks the logical address contained in any PTE to be - entered into the PFT to insure that it is valid and then translates the - logical address into the assigned physical address. - - - - When hypervisor returns the contents of a PTE, the contents of - the RPN are usually architecturally undefined. It is expected that - hypervisor implementations leave the contents of this field as it was - read from the PTE since it cannot be used by the OS to directly access - real memory. The exception to this rule is when the R-XLATE flag is - specified to the H_READ hcall(), then the RPN in the PTE is reverse - translated into the LPN prior to return. - - - - Logical addressing: - LPAR adds another level of virtual address translation managed by - the hypervisor. The OS is never allowed to use the physical address of - its memory this includes System Memory, MMIO space, NVRAM etc. The OS - sees System Memory as N regions of contiguous logical memory. Each - logical region is mapped by the hypervisor into a corresponding block of - contiguous physical memory on a specific node. All regions on a specific - system are the same size though different systems with different amount - of memory may have different region sizes since they are the quantum of - memory allocation to partitions. That is, partitions are granted memory - in region size chunks and if a partition’s OS gives up memory, it - is in units of a full region. On NUMA platforms, groups of regions may be - associated with groups of processors forming logical CECs for allocation - and migration purposes. - Logical addresses are divided into two fields, the logical region - identifier and the region offset. The region offset is the low order bits - needed to represent the region size. The logical region identifier are - the remaining high order bits. - - - - Logical addresses start at zero. When control is initially passed - to the OS from the platform, the first region is the single RMA. The - first region has logical region identifier of zero. This first region is - specified by the first address - length pair of the - “reg” property of the - /memory node of the OF device tree. Subsequent + + + -31 + + + H_PORT_PARM (invalid port number) + + + + + -32 + + + H_MCG_PARM (invalid multicast group) + + + + + -33 + + + H_VL_PARM (invalid virtual lane) + + + + + -34 + + + H_TSIZE_PARM (invalid trace size) + + + + + -35 + + + H_TRACE_PARM (invalid trace buffer) + + + + + -36 + + + H_TRACE_PARM (invalid trace buffer) + + + + + -37 + + + H_MASK_PARM (invalid mask value) + + + + + -38 + + + H_MCG_FULL (multicast attachments exceeded) + + + + + -39 + + + H_ALIAS_EXIST (alias QP already defined) + + + + + -40 + + + H_P_COUNTER (invalid counter specification) + + + + + -41 + + + H_TABLE_FULL (resource page table full) + + + + + -42 + + + H_ALT_TABLE (alternate table already exists / alternate + page table not available) + + + + + -43 + + + H_MR_CONDITION (invalid memory region condition) + + + + + -44 + + + H_NOT_ENOUGH_RESOURCES (insufficient resources) + + + + + -45 + + + H_R_STATE (invalid resource state condition or sequencing + error) + + + + + -46 + + + H_RESCINDED + + + + + -54 + + + H_Aborted + + + + + -55 + + + H_P2 + + + + + -56 + + + H_P3 + + + + + -57 + + + H_P4 + + + + + -58 + + + H_P5 + + + + + -59 + + + H_P6 + + + + + -60 + + + H_P7 + + + + + -61 + + + H_P8 + + + + + -62 + + + H_P9 + + + + + -63 + + + H_NOOP + + + + + -64 + + + H_TOO_BIG + + + + + -65 + + + Reserved + + + + + -66 + + + Reserved + + + + + -67 + + + H_UNSUPPORTED (Parameter value outside of the range + supported by this implementation) + + + + + -68 + + + H_OVERLAP (unsupported overlap among passed buffer + areas) + + + + + -69 + + + H_INTERRUPT (Interrupt specification is invalid) + + + + + -70 + + + H_BAD_DATA (uncorrectable data error) + + + + + -71 + + + H_NOT_ACTIVE (Not associated with an active + operation) + + + + + -72 + + + H_SG_LIST (A scatter/gather list element is + invalid) + + + + + -73 + + + H_OP_MODE (There is a conflict between + the subcommand and the requested operation + notification) + + + + + -74 + + + H_COP_HW (co-processor hardware error) + + + + + -75 + + + H_STATE (invalid state) + + + + + -76 + + + H_RESERVED (a reserved value was specified) + + + + + -77 + + + H_IN_USE (a specified resource is already in use) + + + + + -78 : -255 + + + Reserved + + + + + -256 -- -511 + + + H_UNSUPPORTED_FLAG (An unsupported binary flag bit was + specified. The returned value is -256 - the bit position of the + unsupported flag bit [high order flag bit is 0 etc.]) + + + + + +
+ +
+ Hypervisor Call Functions + + +
+ Page Frame Table Access + All hypervisor Page Frame Table (PFT) access routines are called + using 64 bit linkage conventions and apply to all page sizes that the + platform supports as specified by the + “ibm,processor-page-sizes” property. (See + for more details.) + The Page actual size is encoded in the PFT entry + per the architecture Book IIIs along with the + segment base page size per the + Book IVa. + The hypervisor PFT + access functions carefully update a given Page Table Entry (PTE) with at + least 64 bit store operations since an invalid update sequence could + result in machine checks. To guard against multiple conflicting + allocations of a PTE that could result in a check stop condition, the + hypervisor PTE allocation routine (H_ENTER) reserves the first two (high + order) software PTE bits for use as PTE locks while the low order two + software PTE bits are reserved for OS use (not used by firmware). If a + firmware PTE bit is on, the OS is to assume that the PTE is in use, just + as if the V bit were on. The hypervisor PFT access routines often execute + the tlbie instruction, on certain platforms, this instruction may only be + executed by one processor in a partition at a time, the hypervisor uses + locks to assure this. The tlbie instruction flushes a specific translate + lookaside buffer (TLB) entry from all processors participating in the + protocol. All the processors participating in the tlbie protocol are + defined as a translation domain. All processors of a given partition that + are in a given translation domain share the same hardware PFT. Book III + of the PA specifies the codes sequences needed to safely access the PFT, + in its chapter titled “Storage Control Instructions and Table + Updates”. These code sequences are part of this specification by + reference. The hypervisor PFT access routines are in the critical + performance path of the machine, therefore, extraordinary care must be + given to their performance, including machine dependent coding, minimal + run time checking, and code path length optimization. For performance + reasons, all parameter linkage is through registers, and no indirect + parameter linkage is allowed. This requires special glue code on the part + of the caller to pick up the return parameters. The hypervisor PFT access + routines modify the calling processor’s partition PFT on the + calling node. On NUMA systems, if an LPAR partition spans multiple + Central Electronics Complexes (CECs), the partition’s processors + may be in separate translation domains. Each platform translation domain + has a separate PFT. Therefore, the partition’s OS must modify each + PFT individually. This is done either by making hcall() accesses + specifying the NUMA CEC Cookie (which identifies the translation domain) + in the high order 16 bits of the flags parameter (H_ENTER and H_READ + only) or by issuing the hcall() from a processor within the translation + domain as identified by the processor’s NUMA CEC Cookie field of + the + “ibm,pft-size” property. + The PFT is preallocated based upon the value of the + partition’s PFT_size configuration variable. This configuration + variable is initialized to 4 PTEs per node local page frame and 2 PTEs + per remote node page frame. The size of the PFT per node is communicated + to the partition’s OS image via the + “ibm,pft-size” property of the + node. + The value of the configuration variable + PFT_size consists of two comma separated integers, + the first is the number of hardware PFT entries to allocate per CEC local + page, and the second is the number of hardware PFT entries to allocate + per remote CEC page (if NUMA configured). These allocations are made at + partition boot time based upon the initial partition memory allocation, + based upon specific situations (such as low page table usage or future + need for dynamic memory addition) the OS may wish to override the + platform default values. + + + + R1--1. + + For the LPAR option: The platform must allocate the + partition’s page frame table. The size of this table is determined + by the PFT_size configuration variable in the OS image’s + “common” NVRAM partition. + + + + + R1--2. + + For the LPAR option: The platform must provide the + “ibm,pft-size” property in the processor + nodes of the device tree (children of type + cpu of the + /cpus node). + Register Linkage (For hcall() tokens 0x04 - 0x18) + + + + + + On Call: + + R3 function call token + R4 flags (see ) + R5 Page Table Entry Index (PTEX) + R6 Page Table Entry High word (PTEH) (on H_ENTER only) + R7 Page Table Entry Low word (PTEL) (on H_ENTER only) + + + On Return: + + R3 Status Word + R4 chosen PTEX (from H_ENTER) / High Order Half of old PTE + R5 Low Order Half of old PTE + R6 + + + + + Semantics checks for all hypervisor PTE access routines: + + + + Hypervisor checks that the caller was in privileged mode or + H_Privilege return code. + + + + On NUMA platforms for the H_ENTER and H_READ calls only, the + hypervisor checks that the NUMA CEC Cookie is within the range of values + assigned to the partition else return H_Parameter. + + + + Hypervisor checks that the PTEX is zero or greater and less than + the partition maximum, else H_Parameter return code. + + + + Hypervisor checks the logical address contained in any PTE to be + entered into the PFT to insure that it is valid and then translates the + logical address into the assigned physical address. + + + + When hypervisor returns the contents of a PTE, the contents of + the RPN are usually architecturally undefined. It is expected that + hypervisor implementations leave the contents of this field as it was + read from the PTE since it cannot be used by the OS to directly access + real memory. The exception to this rule is when the R-XLATE flag is + specified to the H_READ hcall(), then the RPN in the PTE is reverse + translated into the LPN prior to return. + + + + Logical addressing: + LPAR adds another level of virtual address translation managed by + the hypervisor. The OS is never allowed to use the physical address of + its memory this includes System Memory, MMIO space, NVRAM etc. The OS + sees System Memory as N regions of contiguous logical memory. Each + logical region is mapped by the hypervisor into a corresponding block of + contiguous physical memory on a specific node. All regions on a specific + system are the same size though different systems with different amount + of memory may have different region sizes since they are the quantum of + memory allocation to partitions. That is, partitions are granted memory + in region size chunks and if a partition’s OS gives up memory, it + is in units of a full region. On NUMA platforms, groups of regions may be + associated with groups of processors forming logical CECs for allocation + and migration purposes. + Logical addresses are divided into two fields, the logical region + identifier and the region offset. The region offset is the low order bits + needed to represent the region size. The logical region identifier are + the remaining high order bits. + + + + Logical addresses start at zero. When control is initially passed + to the OS from the platform, the first region is the single RMA. The + first region has logical region identifier of zero. This first region is + specified by the first address - length pair of the + “reg” property of the + /memory node of the OF device tree. Subsequent regions each have their own address - length pair. At initial program load time, the logical region identifiers are sequential starting at zero but over time, with dynamic memory reconfiguration, holes may appear in @@ -5656,9 +6031,15 @@ hcall ( const uint64 H_REMOVE, initialize the page from one or more compressed data blocks and optionally (checksum flag) check the end to end block data integrity prior to adding the entry to the page table. If the compression flag is - not set the checksum flag is ignored. + not set the checksum flag is ignored. If the Memory Usage Instrumentation + (MUI) option is implemented, + flags allow for initializing MUI state for the page when the translation is + entered. - + Syntax: + + + + Parameters: @@ -5737,9 +6120,13 @@ hcall ( const uint64 H_ENTER, - For the PFO option: the compression flag initializes the page - content from a compression buffer and the checksum flag checks for end to - end compression buffer data integrity. + For the MUI option: The HBA bits specify settings of implementation dependent PTE bits and + associated MUI array entries for the page who’s translation is being entered. + + + + For the MUI option: The Affinity-Clear and Page-Age-Clear bits clear associated MUI array + entries for the page who’s translation is being entered. @@ -5986,6 +6373,27 @@ hcall ( const uint64 H_ENTER, The hypervisor selects a PTE within the page table entry group using the following. + + + If the MUI option is enabled + { + Switch (HBA flags field) + { + Case ‘0b11: return H_UNSUPPORTED_FLAG; + Case ‘0b10: + enable implementation dependent HBA update bit in PTE; + set implementation dependent PTE PUT field to previous time; + Set Reference History Bit Array entry for physical page to configured initial + value; + Case ‘0b01: + enable implementation HBA update in PTE; + set implementation dependent PTE PUT field to previous time; + Default: disable implementation dependent HBA update bit in PTE; + } + If the Affinity-Clear flag is on clear the MUI ALA for the page; + If the Page-Age-Clear flag is on clear the MUI PAG for the page; + } + @@ -6070,7 +6478,11 @@ hcall ( const uint64 H_ENTER, This hcall returns the contents of a specific PTE in registers R4 and R5. - + + Syntax: + + + Parameters: @@ -6175,13 +6587,16 @@ hcall ( const uint64 H_ENTER, This hcall clears the modified bit in the specific PTE. The second double word of the old PTE is returned in R4. - + Syntax: + - + + Parameters: @@ -6276,13 +6691,16 @@ hcall ( const uint64 H_CLEAR_MOD, /* Clears the PTE Modified bit */ This hcall clears the reference bit in the specific PTE. The second double word of the old PTE is returned in R4. - + Syntax: + - + + Parameters: @@ -6346,6 +6764,8 @@ hcall ( const uint64 H_CLEAR_REF, /* Clears the PTE Reference bit */ H_PROTECT This hcall sets the page protect bits in the specific PTE. + + Syntax: - + + Parameters: @@ -6479,7 +6900,9 @@ hcall ( const uint64 H_PROTECT, /* Changes the page protection specification */ the specific page table entries. Prototype: - + Syntax: + - Translation specifiers: - Each is 16 bytes long made up of two 8 byte double words; a - translation specifier high and a translation specifier low. + Translation specifiers: + Each is 16 bytes long made up of two 8 byte double words; a + translation specifier high and a translation specifier low. - - - Translation Specifier High double word: + + + Translation Specifier High double word: - - - First byte (0) is a control/status byte: + + + First byte (0) is a control/status byte: - - - High order two bits (0 and 1) are type code: + + + High order two bits (0 and 1) are type code: - - - 00 Unused -- if found stop processing and return - H_PARAMETER - - - - 01 Request -- Processes As per H_REMOVE as modified by low order - two control bits. - - - - 10 Response -- written by hypervisor as a return status from - processing individual “request” translation specifier - - - - 11 End of String -- if found stop processing and return - H_Success. - - - - - - Next two bits (2 and 3) are response code (in response to - processing an individual “request” translation specifier - (type code modified to 10)): + + + 00 Unused -- if found stop processing and return + H_PARAMETER + + + + 01 Request -- Processes As per H_REMOVE as modified by low order + two control bits. + + + + 10 Response -- written by hypervisor as a return status from + processing individual “request” translation specifier + + + + 11 End of String -- if found stop processing and return + H_Success. + + + + + + Next two bits (2 and 3) are response code (in response to + processing an individual “request” translation specifier + (type code modified to 10)): - - - 00 Success -- the specified translation was removed as per - H_REMOVE with the PTE's RC bits in the next two status bits. - - - - 01 Not found -- the specified translation was not found as per - H_REMOVE. - - - - 10 H_PARM -- one or more of the parameters of the specified - translation were invalid per H_REMOVE -- processing of the bulk entries - stops at this point and the hypervisor returns H_PARAMETER. - - - - 11 H_HW -- The hardware experienced an uncorrected error - processing this translation specifier -- processing of the bulk entries - stops at this point and the hypervisor returns H_HARDWARE. - - - - - - Next two bits (4 and 5) are the Reference/Change bits from the - removed PTE (These bits are only valid if bits 0-3 are 1000): - - - - Low order two bits (6 and 7) are request modification - flags: + + + 00 Success -- the specified translation was removed as per + H_REMOVE with the PTE's RC bits in the next two status bits. + + + + 01 Not found -- the specified translation was not found as per + H_REMOVE. + + + + 10 H_PARM -- one or more of the parameters of the specified + translation were invalid per H_REMOVE -- processing of the bulk entries + stops at this point and the hypervisor returns H_PARAMETER. + + + + 11 H_HW -- The hardware experienced an uncorrected error + processing this translation specifier -- processing of the bulk entries + stops at this point and the hypervisor returns H_HARDWARE. + + + + + + Next two bits (4 and 5) are the Reference/Change bits from the + removed PTE (These bits are only valid if bits 0-3 are 1000): + + + + Low order two bits (6 and 7) are request modification + flags: + + + + 00 absolute -- remove the specified PTEX entry + unconditionally + + + + 01 andcond -- remove the specified PTEX entry as with the andcond + flag of H_REMOVE + + + + 10 AVPN -- remove the specified PTEX entry as with the AVPN flag + of H_REMOVE + + + + 11 not used -- if found stop processing and return + H_PARAMETER. + + + + + + + + Bytes 1 through 7 are the PTEX (PFT byte offset divided by + 16) + + + + + + Translation Specifier Low double word: + + + + Bytes 0 through 7 are the AVPN as per H_REMOVE + + + + + + + + Semantics: + + + + For each translation specifier, while the translation specifier + is not “end of string”: + + + + Check that the PTEX accesses within the PFT else set H_PARM + response status in the specific translation specifier high register and + return H_Parameter + + + + If the AVPN flag is set, and the AVPN parameter bits 0-56 do not + match that of the specified PTE then set response status Not found in the + specific translation specifier high register, Continue. + + + + If the andcond flag is set, the AVPN parameter is bit anded with + the first double word of the specified PTE (after bits 57-63 of the PTE + have been masked), if the result is non-zero, then set response status + Not found in the specific translation specifier high register, Continue. + (Note the low order 7 bits of the AVPN parameter should be zero otherwise + the likely result is a response status of Not found). + + + + The hypervisor Synchronizes the PTE specified by the PTEX. + + + + Use the architected “Deleting a Page Table Entry” + sequence. + + + + Use the proper tlbie instruction for the page size within a + critical section protected by the proper lock (per large page bit in the + specified PTE). + + + + The synchronized value of the old PTE RC bits ends up in bits 4 + and 5 of the individual translation specifier high register along with + success response status. + + + + + + return H_Success + + + + +
+ +
+ H_BLOCK_REMOVE + + This hcall removes up to eight sequential virtual + page table entries. Some platforms that support this hcall() might remove + fewer than 8 entries for a given actual page size / base page + size combination as communicated by the “Block Invalidate + Characteristics” system parameter (see + ). + The virtual pages are all within + the same naturally aligned 8 page virtual address block and + have the same page and segment size encodings. The AVA parameter, + if used, covers the entire block of virtual page + addresses. If another processor is currently accessing + the page table entry, the entry is not removed. The availability of + is hcall() might change after partition migration, the + caller should be prepared for an H_Function return code. The + PTEX field of the translation specifier parameters + identifies the specific page table entries. + + + Syntax: + + + The AVA parameter is the 8 byte AVPN as per H_REMOVE. + + Each Translation Specifier is 8 bytes long: + + + H_BLOCK_REMOVE Translation Specifier + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Byte 0 + + + Byte 1 + + + Byte 2 + + + Byte 3 + + + Byte 4 + + + Byte 5 + + + Byte 6 + + + Byte 7 + + + + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + + + + + + Control + + + 0 + + + Reserved + + + PTEX (PFT byte offset divided by 16) + + + + +
+ + + H_BLOCK_REMOVE Control Byte Format + + + + + + + + + + + + + Control + + + Description + + + + + + Type +   +   +   +   +   +   +   + + + 00 + Unused + + + 01 + Request + + +   +   + 0 + absolute -- remove the specified PTEX entry unconditionally + + + 1 + AVPN -- remove the specified PTEX entry as with the AVPN flag of H_REMOVE + + + Page State +   + + + 0 + 0 + Inhibit page usage state change + + + 0 + 1 + Reserved + + + 1 + 0 + For CMO option set page usage state to “Unused” if Success + + + 1 + 1 + For CMO option set page usage state to “Loaned” if Success + + +   + + + 10 + Response + + +   + 0 + 0 + 0 + Success -- the specified translation was removed as per H_REMOVE + with the PTE's RC bits in the next two status bits. + + + 0 + 0 + 1 + Not found -- the specified translation was either not found a + s per H_REMOVE, Invalid (V bit = 0), or entry was “bolted” (PTE bit 59 = 1) + + + 0 + 1 + 0 + H_PARM Parameter is invalid + + + 0 + 1 + 1 + Inconsistent Page/Segment Size (does not match the L||LP and B + fields of the block anchor Page Table Entry) + + + 1 + 0 + 0 + Busy (The page table entry is being modified by another processor) + + + 1 + 0 + 1 + Cross Boundary (The page table entry crosses an 8 page virtual address boundary) + + + 1 + 1 + 0 + Beyond Capacity (The page table entry exceeded the number supported on this platform) + + + 1 + 1 + 1 + The hardware experienced an uncorrected error processing this translation specifier -- + processing of the bulk entries stops at this point and the hypervisor returns H_HARDWARE. + + +   + R + Reference bit from the removed PTE (bit is only valid if bits 0-4 are 10000) + + +   + R + Reference bit from the removed PTE (bit is only valid if bits 0-4 are 10000) + + +   + + + 11 + End of String -- if found stop processing and return the accumulated return code. + + + +
+ + + + Semantics: - - - 00 absolute -- remove the specified PTEX entry - unconditionally - - - - 01 andcond -- remove the specified PTEX entry as with the andcond - flag of H_REMOVE - - - - 10 AVPN -- remove the specified PTEX entry as with the AVPN flag - of H_REMOVE - - - - 11 not used -- if found stop processing and return - H_PARAMETER. - - - - - + + + Initialize return code to H_Success (overwritten if appropriate) + + + Initialize “anchored” flag to false and PTECOUNT to zero. + + + For each translation specifier, while the translation specifier type is not “end of string”: - - Bytes 1 through 7 are the PTEX (PFT byte offset divided by - 16) - - - - - - Translation Specifier Low double word: - - - - Bytes 0 through 7 are the AVPN as per H_REMOVE - - - - + + + If the translation specifer type is not “Request” Return H_PARAMETER. + + + Check that the PTEX accesses within the PFT else set H_PARM response status in the specific translation specifier + high register set return code to H_PARTIAL and Continue. + + + If the lock for the associated page table entry can not be immediately obtained, then set the TSn response code to + “Busy”, set return code to H_PARTIAL and Continue. + + + If the PTEX specified entry is either invalid (PTE V bit = 0) or “bolted” (PTE bit 59 = 1) then set response status + “Not found” in the specific translation specifier high register, set return code to H_PARTIAL and Continue. + + + Check that actual page size / base page size combination of the PTEX specified entry is supported for + H_BLOCK_REMOVE as communicated by the “Block Invalidate Characteristics” system parameter else set + H_PARM response status in the specific translation specifier high register set return code to H_PARTIAL and + Continue. + + + If the AVPN flag is set, and the AVPN parameter bits 0-56 do not match that of the specified PTE then set response + status “Not found” in the specific translation specifier high register, set return code to H_PARTIAL and + Continue. + + + If NOT Anchored: + + + + then: + + + + Establish the block L||LP + + + Establish the block segment size encoding + + + For the CMO option: if the TS Control byte Page State bits are a reserved value then set H_PARM response + status in the specific translation specifier high register, set return code to H_PARTIAL and Continue; else If + the block segment encoding is an MPSS segment then set the page usage state for the large page per the + CMO Page State bits of the TS Control byte; else set the page usage state per the CMO Page State bits of the + TS specified page per the TS Control byte. + + + Establish the block plus high order virtual address + + + Establish the number of TLBs that the platform can invalidate in one operation from the associated page table + entry + + + Set the “anchored” flag to true; + + + + + else: + + + If the associated page table entry L||LP and segment size encoding does not match the established anchored + values then set the TSn response code to “Inconsistent Page/Segment Size“, set return code to H_PARTIAL + and Continue. + + + If the associated page table entry high order virtual address of the 8 page block does not match the established + anchored values then set the TSn response code to “Cross Boundary“, set return code to H_PARTIAL + and Continue. + + + If PTECOUNT is greater than the number of TLBs that the platform can invalidate in one operation, then set + the TSn response code to “Beyond Capacity“, set return code to H_PARTIAL and Continue. + + + For the CMO option: if the TS Control byte Page State bits are a reserved value then set H_PARM response + status in the specific translation specifier high register, set return code to H_PARTIAL and Continue; else if + the block segment size encoding is not MPSS then set the page usage state per the CMO Page State bits of + the TS Control byte. + + + + + + + Add the PTEX to the validated list of PTEX’s to be removed + + + Increment PTECOUNT + + + + + The hypervisor resets the valid bit in the PTEs specified by the validated list of PTEX’s to be removed. + + + The hypervisor issues a single instance of the PTE Synchronization sequence outlined in the + architecture Book IIIS under “Deleting a Page Table Entry” using the proper tlbie instruction for the page size within a critical + section protected by the proper lock (per large page bit in the specified PTE) to cover all the PTEs specified by + the validated list of PTEX’s to be removed. + + + The synchronized value of the old PTE RC bits, for the PTEs specified by the validated list of PTEX’s to be removed, + ends up in bits 5 and 6 of the individual translation specifier high register along with success response status. + + + Release acquired page table entry locks. + + + Return the accumulated return code and TS values. + + +
- - Semantics: - - - - For each translation specifier, while the translation specifier - is not “end of string”: - - - - Check that the PTEX accesses within the PFT else set H_PARM - response status in the specific translation specifier high register and - return H_Parameter - - - - If the AVPN flag is set, and the AVPN parameter bits 0-56 do not - match that of the specified PTE then set response status Not found in the - specific translation specifier high register, Continue. - - - - If the andcond flag is set, the AVPN parameter is bit anded with - the first double word of the specified PTE (after bits 57-63 of the PTE - have been masked), if the result is non-zero, then set response status - Not found in the specific translation specifier high register, Continue. - (Note the low order 7 bits of the AVPN parameter should be zero otherwise - the likely result is a response status of Not found). - - - - The hypervisor Synchronizes the PTE specified by the PTEX. - - - - Use the architected “Deleting a Page Table Entry” - sequence. - - - - Use the proper tlbie instruction for the page size within a - critical section protected by the proper lock (per large page bit in the - specified PTE). - - - - The synchronized value of the old PTE RC bits ends up in bits 4 - and 5 of the individual translation specifier high register along with - success response status. - - - - - - return H_Success - - -
@@ -7277,7 +8211,10 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */
H_SET_SPRG0 - + + Syntax: + + Parameters: @@ -7299,8 +8236,11 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ for newer implementations. - - + + Syntax: + + + Semantics: @@ -7350,10 +8290,14 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */
H_PAGE_INIT - + Syntax: + + + Parameters: @@ -7451,12 +8395,15 @@ hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */ that it allows setting breakpoints for LPAR addresses that the hypervisor had to preclude using the previous facility. - + Syntax: + + Semantics: @@ -7520,7 +8467,10 @@ hcall ( const uint64 H_SET_XDABR, /* Function Token */ “cpu-version” property. presents the valid parameter ranges for the architectural level reported in the - “cpu-version” property. + “cpu-version” property + and the LoPAR architecture level as reported in the + “/chosen” property. + Setting breakpoints: A breakpoint is set for a hardware tread. Should the hardware thread complete an instruction who's effective address matches that of the set breakpoint a trace interrupt is signaled. @@ -7549,8 +8499,16 @@ hcall ( const uint64 H_SET_XDABR, /* Function Token */ mode setting. The desired AIL mode is encoded in the two low order mflags bits (all other mflags bits are 0) while both value1 and value2 parameters are zero. + + The POWER ISA requires that the setting the LPCR ILE bit be the same + in all partition processors when not in hypervisor mode thus all partition + processors need to be operating with MSR[EE] = 0 when changing LPCR ILE so + that the OS can change the contents of the interrupt vectors prior to any + interrupts being taken in the new mode. - + Syntax: + + Semantics: - switch (resource) { - case 0: /* not used / - return H_P2; - break; - case 1: /* Completed Instruction Address Breakpoint Register - */ - if value2 <> 0 the return H_P4; - if mflags <> 0 then return H_UNSUPPORTED_FLAG; - If low order two bits of value1 are 0b11 then return H_P3; /* not - hypervisor instruction address */ - move value 1 into CIABR; /* note the value2 parameter is not used - for this resource */ - break; - case2: /* Watch point 0 registers */ - if mflags <> 0 then return H_UNSUPPORTED_FLAG; - If value2 bit 61 == 0b1 then return H_P4; /* not hypervisor - addresses */ - move value1 into DAWR0; - move value2 into DAWRX0; - break; - case3: / * Address Translation Mode on Interrupt * / - if value1 < > 0 then return H_P3; - if value2 < > 0 then return H_P4; - switch (mflags) { - case 0: / * IR = DR = 0 * / - Set LPCR AIL field of calling partition processors to 0b00; - break; - case 1: / * reserved * / - return H_UNSUPPORTED_FLAG ( - 318); - break; - case 2: / * IR = DR = 1 interrupt vectors at E.A. 0X18000 * - / - Set LPCR AIL field of calling partition processors to 0b10; - break; - case 3: / * IR = DR = 1 interrupt vectors at E.A. 0XC000 0000 0000 - 4000 * / - Set LPCR AIL field of calling partition processors to 0b11; - break; - default: return H_UNSUPPORTED_FLAG (value based on most - convenient - unsupported bit); - break; - default: - return H_P2; - break; } + switch (resource) { + case 0: /* not used / + return H_P2; + break; + case 1: /* Completed Instruction Address Breakpoint Register */ + if value2 <> 0 the return H_P4; + if mflags <> 0 then return H_UNSUPPORTED_FLAG; + If low order two bits of value1 are 0b11 then return H_P3; /* not hypervisor + instruction address */ + move value 1 into CIABR; /* note the value2 parameter is not used for this resource */ + break; + case2: /* Watch point 0 registers */ + if mflags <> 0 then return H_UNSUPPORTED_FLAG; + If value2 bit 61 == 0b1 then return H_P4; /* not hypervisor addresses */ + move value1 into DAWR0; + move value2 into DAWRX0; + break; + case3: / * Address Translation Mode on Interrupt * / + if value1 <> 0 then return H_P3; + if value2 <> 0 then return H_P4; + switch (mflags) { + case 0: / * IR = DR = 0 * / + Set LPCR AIL field of calling partition processors to 0b00; + break; + case 1: / * reserved * / + return H_UNSUPPORTED_FLAG ( - 318); + break; + case 2: / * IR = DR = 1 interrupt vectors at E.A. 0X18000 * / + Set LPCR AIL field of calling partition processors to 0b10; + break; + case 3: / * IR = DR = 1 interrupt vectors at E.A. 0XC000 0000 0000 4000 * / + Set LPCR AIL field of calling partition processors to 0b11; + break; + default: + return H_UNSUPPORTED_FLAG (value based on most convenient unsupported bit); + break; +/* Starting with PAPR Version 2.8 add the following */ + case 4: / * Set the LPCR ILE bit. * / + if (value1) return H_P3; + if (value2) return H_P4; + switch (mflags) { + case 0: + Marshal all partition processors into the hypervisor + If any partition processors were not running MSR[EE] = 0 then + Release all marshaled processors and return bad_mode + Else + On each partition processor set LPCR[ILE] = 0 + return H_Success; + case 1: + Marshal all partition processors into the hypervisor + If any partition processors were not running MSR[EE] = 0 then + Release all marshaled processors and return bad_mode + Else + On each partition processor set LPCR[ILE] = 1 + return H_Success; + default: + return H_UNSUPPORTED_FLAG (value based on most convenient unsupported bit); + break; + default: + return H_P2; + break; } H_SET_MODE Parameters per ISA Level - + - + - ISA level + PAPR level @@ -7657,8 +8632,8 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ - - 2.07 + + 2.7 1 @@ -7767,6 +8742,9 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ + + 2.8 + All Others @@ -7795,13 +8773,201 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ For implementations supporting POWER ISA level 2.07 and beyond: the platform must implement the H_SET_MODE hcall() per the syntax and semantics of section - . + per the LoPAR level supported. + +
+ Implementation Dependent Optimizations + + All platforms contain implementation specific switches and values that effect the performance of the platform. The default + settings for switches and values are tuned during platform development to achieve the desired performance characteristics + across a wide range of workloads. However, the performance of specific workloads might be further + optimized by adjusting some of these implementation specific switches and values when those workloads are being + run. Other of these switches and values might have negative effects on other platform workloads, so those switches and + values are protected from modification lest innocent partitions become victims of one of their neighbors. LoPAR version + 2.8 and above provide the hcall()s defined below to set a subset of the implementaion specific switches and adjust a + subset of the tuning values within a range that has been proven to be safe. The caller is expected to understand the + switch banks and resources implemented by the specific platform and the functinality of each individual switch and resource. + + Special consideration is required of the caller of these functions during partition migration and micro-checkpoint/ + failover operations since the underlying implementation might change. During these operarations, the implementation + dependent switches and values are set to their default values for the implementation that is receiving the + partition. After a migration or failover event the availability of the Implementation Dependent Optimization hcall()s + might change, along with the resources and/or switch banks that might be adjusted, and the supported values for those + adjustments. + +
+ H_ADJUST_RESOURCE + + This hcall() is used to adjust the value of a given implementation dependent resource in contiguous unit steps between + the minimum and maximum supported values. These steps are not necessarily uniform either in physical values set into + the implementation dependent resource or the resultant effect they have on workload performance. + + + Syntax: + + + + + Semantics: + + + If the value of the Resource parameter is zero then return H_PARAMETER + + + If the value of the Resource parameter is greater than the maximum defined + value then return H_RESERVED + + + If the value of the Resource paramter is not supported on this implementation + then return H_UNSUPPORTED + + + RC = H_Success + + + Current = current value of the Resource + + + If Current + Value > max supported value of Resource then + + + { RC = H_Constrained ; + + + Current = max supported value of Resource } + + + + + If Current + Value < min supported value of Resource then + + + { RC = H_Constrained ; + + + Current = min supported value of Resource } + + + + + Set Resource to Current + + + On return: + + + R3: Contains Return Code (RC) + + + R4: Contains the Resource value (Current) (Return codes H_Success & H_Constrained) + + + R5: Contains the number of steps to minimum supported resource value + + + R6: Contains the number of steps to maximum Suppported resource value + + + + + +
+ +
+ H_SET_SWITCHES + + This hcall() provides for the setting of an implementation dependent subset of the switches in an implementation dependent + bank of switches. + + + Syntax: + + + + + Semantics: + + + If the value of the Bank parameter is zero then return H_PARAMETER + + + If the value of the Bank parameter is greater than the maximum defined + value then return H_RESERVED + + + If the value of the Bank paramter is not supported on this implementation + then return H_UNSUPPORTED + + + If (Mask & not (Supported-bits-in[Bank]) ) then RC = H_Constrained + else RC = H_Success + + + Turn on the bits in switches[Bank] that are ones in all three of + Supported-bits-in[Bank], Mask, and Setting + + + Turn off the bits in switches[Bank] that are ones in both + Supported-bits-in[Bank] and Mask but are zeros in Setting + + + On return: + + + R3: Contains Return Code (RC) + + + R4: Contains the Mask value representing all switches who's setting is supported for the bank + + + R5: Contains the Bank value (Return codes H_Success & H_Constrained) + + + + + +
+
@@ -7814,8 +8980,11 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
H_LOGICAL_CI_LOAD - - + + Syntax: + + + Parameters: @@ -7867,10 +9036,13 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
H_LOGICAL_CI_STORE - + Syntax: + + Parameters: @@ -7957,11 +9129,17 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ H_HYPERVISOR_DATA hcall() need only return data in the firmware working storage that is not contained in the PFT or TCE tables since the contents of these tables are available to the OS. + + Starting with LoPAR Version 2.8 PAPR platforms support the + H_CLEAR_HPT hcall() independent of Client Architecture support negotiation.
H_HYPERVISOR_DATA - + + Syntax: + + Parameters: @@ -8001,6 +9179,68 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ H_Parameter.
+ +
+ H_CLEAR_HPT + + This hcall() clears the hash page table (HPT) for a partition in preparation for a restart. The Virtual Real + Mode Area and Partition Adjunct mappings are exempted. The performance class of this hcall() is + “Terminal”, that is, it is allowed to take as long as it needs to perform the operation in a single call, + however, it is also allowed to return H_CONTINUE, at which time the caller needs to again make the call + until it receives H_Success else the partition HPT might be left in an inconsistent state. Never the less, the + reason for this hcall() is to optimize the performance of this function relative to a series of H_REMOVE + calls, therefore, hypervisors are encouraged to perform portions of the function in parallel using as many + partition processor threads as is practical. + + The hypervisor clears the partition’s HT entries (sets them to invalid) except for those entries mapping the + VRMA, or a Partition Adjunct, performs a TLBIA on all partition processor threads, and returns H_Success + on the calling thread. + + To avoid translation exceptions, attempting to access pages whose translations are being cleared, all OS + processor threads should be operating MSR[IR] = MSR[DR] = MSR[PR] = 0b0. Any attempt to use one of + the HPT access hcall(s) (See ) during the + clearing process might result in the an H_Busy return code, and/or the processor might be pressed into + service clearing the HPT. + + + Syntax: + + + + + Semantics: + + + + Disable other HPT access hcall()s + + + + For each HPT entry + + + + If the entry does not map the VRMA or Partition Adjunct clear the V bit + + + + + + For each partition processor perform a TLBIA + + + + Enable other HPT access hcall()s + + + + Return H_Success + + + +
@@ -8017,7 +9257,10 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ but not limited to lost interrupts, and excessive phantom interrupts. - + + Syntax: + + Parameters: @@ -8068,7 +9311,10 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
H_CPPR - + + Syntax: + + Parameters: @@ -8107,7 +9353,10 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
H_IPI - + + Syntax: + + Parameters: @@ -8165,7 +9414,10 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
H_IPOLL - + + Syntax: + + Parameters: @@ -8214,7 +9466,9 @@ hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */ implementations implement only H_XIRR, returning H_Function for a call to H_XIRR-X. POWER8 implementations also implement H_XIRR-X. - + Syntax: + + Parameters: @@ -8396,7 +9651,9 @@ hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external */
H_MIGRATE_DMA - + Syntax: + - + Parameters: @@ -8790,7 +10047,9 @@ hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA H_PERFMON To manage the Performance Monitor Function: - + Syntax: + + Parameters: @@ -10805,7 +12065,22 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin 0xB1 - 7 + 1 + + + Maintain EBB registers: + =0 architected state of the event based branch facility may be + discarded at any time, + =1 architected state of the event based branch facility must be + maintained, all other values are reserved + + + + + 0xB2 + + + 6 Reserved For LoPAR Expansion @@ -11222,7 +12497,7 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin 8 - .Reserved for Firmware Use + Reserved for Firmware Use @@ -11371,6 +12646,9 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin 8: The virtual processor was dispatched at the faulting instruction following a virtual partition memory page fault. + 10: The virtual processor was dispatched at the privileged + doorbell interrupt vector location to handle a privileged + doorbell interrupt. @@ -11954,7 +13232,9 @@ hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and correspondin compromised. The syntax of the H_REGISTER_VPA hcall() is given below. - + Syntax: + + Semantics: @@ -15845,8 +17126,13 @@ hcall ( const H_GET_MPP_X /* Returns in R4-R10 extended Memory Performance */ - R8: Reserved shall be set to zero - shall not be read by - the caller + R8: If the calling partition is authorized to see pool + wide statistics (set by means that are beyond the scope of LoPAR) + then, the total number of the calling partition’s + memory pool bytes currently in use backing the pool's partition + logical memory (this value represents the net usage + after any and all savings from deduplication or any other future + means the hypervisor may employ) else set to 0. @@ -17124,48 +18410,389 @@ hcall ( const uint64 H_VPM_PSTAT /* Returns the memory pool performance statisti Place in R8 the summation of the I/O mapped memory of all active partition served by the memory pool. - + + + Place in R9 the summation of the logical real memory of all + active partitions served by the memory pool. + + + + + + Return H_Success. + + + +
+
+
+ +
+ Logical Partition Control Modes + Selected logical partition control modes may be modified by the + client program. + +
+ Secondary Page Table Entry Group (PTEG) Search + The page table search algorithm, described by the + , consists of searching for a + Page Table Entry (PTE) in up to two PTEGs. The first PTEG searched is the + “primary PTEG”. If a PTE match does not occur in the primary + PTEG, the hardware may search the “secondary PTEG”. If a PTE + match is not found in the searched PTEGs, the hardware signals a + translation exception. + Code is not required to place any PTEs in secondary PTEGs. + Therefore, if a PTE match does not occur in a primary PTEG there is no + need for the hardware to search a secondary PTEG to determine that a + search has failed. The “Secondary Page Table Entry Group” bit + of + “ibm,client-architecture-support” allows + code to indicate that there is no need to search secondary PTEGs to + determine that a PTE search has failed. +
+ +
+ Memory Table Translation Option Exploitation + + Starting with platforms build upon POWER processors supporting ISA level 3.0, + the platform supports the In-Memory Table Translation option. This option allows + the memory management unit to perform effective to physical address translation + based off of a single tree of in-memory translation tables, rooted by a single + physical memory address pointer. The option also supports two level radix tree + page tables as well as traditional POWER hash page tables. As initially configured, + partitions that use hash page tables run with legacy Segment Lookaside Buffers + (LPCR [UPRT] = FALSE). To fully exploit the In-Memory Table Translation option, + the hash page table client program registers a process table from its own memory + which sets (LPCR [UPRT] = TRUE). On the other hand, radix page table client programs + need to register a process table before they turn on address translation. + + Each guest partition in the system, may register, within the tree of in-memory + translation tables, its own table (process table) which controls translation of its + process effective addresses to guest virtual / real. The process table is then used + by nest memory management unit for nest accelerator and CAPI attached device accesses, a + nd optionally for processor memory management unit translations. Additionally the + platform might support the client program to directly invalidate cached process + table translation data (when the client program modifies the in-memory table). + If the platform does not support the client program directly issuing process + table cache invalidate instructions, then the client program must use the set + of in-memory table cache invalidate hcall()s in sections + and . + + Note: + The CAS option vector processing associated with the In-Memory + Table Translation option (vector 5 byte 23) carries a special semantic. + +
+ H_CLEAN_SLB + + The Segment Lookaside Buffers (SLB) are a software managed + coherency cache of the per process segment table. The client may + directly issue instructions to clear the SLB on the issuing processor; + however, clearing entries on other processors or the nest memory + management unit requires hypervisor assistance. The H_CLEAN_SLB hcall() + provides the client program with the means for clearing SLB + contents that might be stale. The platform provides through the flags parameter + options as to the scope of the entries that are cleaned, these include: + + + + Clean the nest MMU SLBs of all entries associated with a + specified caller process (esid parameter is set to zero). + + + + Clean all platform SLBs of a specific ESID for a specified caller + process (flags parameter C and B fields specify SLB Class and Size respectively). + + + + + Syntax: + + + + + + + Semantics: + + + + If a reserved flags bit == TRUE return H_Parameter + + + + If flags[62] == flags[63] return H_Parameter + + + + If flags[63] and esid <> 0 return H_P3 + + + + Validate that the calling partition is not mounting a denial of + service attack else return H_LongBusyOrder1mSec. + + + + Perform the following sequence: + + + ptesync + + + If flags[62] then slbieg with RS = pid parameter || + caller’s LPID, RB= esid || C || 0b0 || B || 0b0 || 0x000000 + + + If flags[63] then slbiag with RS = pid parameter || caller’s LPID + + + eieio + + + slbsync + + + ptesync + + + + + + Return H_SUCCESS. + + + +
+ +
+ H_INVALIDATE_PID + + The H_INVALIDATE_PID hcall() invalidates any system translate lookaside + buffer entries from the caller’s specified (pid parameter) process table entry. + + + Syntax: + + + + + + Semantics: + + + + If flags [0:61] <> 0 return H_Parameter + + + + Validate that the calling partition is not mounting a denial of + service attack else return H_LongBusyOrder1mSec. + + + + RB = 0x400 /* Invalidation Selector (IS) = 01 (Invalidate matching PID.) */ + + + + If flags[62] then RB = RB + RB /* Invalidation Selector + (IS) = 10 (Invalidate matching LPID.) */ + + + + Perform the following sequence: + + + ptesync + + + tlbie (RIC=2, PRS=1, R=flags[63]), RS=pid||caller’s_LPID, RB + + + eieio + + + tlbsync + + + ptesync + + + + + + Return H_SUCCESS. + + + +
+ +
+ H_REGISTER_PROCESS_TABLE + + This hcall() is used by the client program to manage the its virtual + address translation mode including registration of its process table. The + calling program needs to be prepared for the change in address translation + that is being requested, for instance, the calling program might choose to + be running with relocation off and with all other processors either spinning + with relocation off or in the stopped state. + + The caller might need to invoke the H_REGISTER_PROCESS_TABLE hcall() + multiple times for it to return with a return code of H_Success. Upon + receiving a return code of H_LongBusyOrder10mSec, the caller should attempt + to invoke H_REGISTER_PROCESS_TABLE in 10mSec with the same parameter values + used on the previous H_REGISTER_PROCESS_TABLE hcall(). Invoking + H_REGISTER_PROCESS_TABLE with a different parameter values indicates + that the caller wants to transition to the parameter values of the most + recent H_REGISTER_PROCESS_TABLE call. + + The platform may implement a subset of the functions implied by the + flags parameter definition below. This subset is reported in the value of + byte 23 of the + “ibm,architecture-vec-5” + property of the + /chosen node. A + request for an unimplemented function results in an H_Parameter return code. + + + Syntax: + + 0b11 then the following parameters shall */ + /* be = 0 else */ + uint64 base, /* Base address of the process table */ + /* For flags 61 = 0 the VSID number of a one terabyte */ + /* segment (right justified in the register) */ + /* For flags 61 = 1 the 4K aligned guest real address */ + uint64 page_size, /* For flags 61 = 0 Size of the pages within the table */ + /* encoded as per the L||LP device tree encoding */ + /* else = 0 */ + uint64 table_size); /* Size of the process table in bytes */ + /* Encoded as the integer */ + /* (log2 (total table length in bytes)) – 12 */ + /* (table_size <= 24) */]]> + + + + + Semantics: + + + + Validate that no reserved flags parameter bits are TRUE and that the + defined bits setting is supported else RETURN H_Parameter. + + + + If “flags” indicate change to process table (flags[59] is TRUE) then: + + + + If “flags” indicate deregistration (flags[58] is FALSE) then set + Partition_Table[calling-partition,word_2] to a platform dependent + benign value; else – Based upon the mode specified in “flags[61-62]”: + + + + Validate “base” parameter else RETURN to H_P2 + + + + Validate “page_size” parameter relative to platform + support else RETURN H_P3 + + + + Validate (0 => “table_size” parameter <=24) else RETURN H_P4 + + + + Set Partition_Table[calling-partition,word_2] to the value + specified by the “flags[61-62]”, “base”, “page_size”, and “table_size” parameters. + + + + Endif + + + + - Place in R9 the summation of the logical real memory of all - active partitions served by the memory pool. + Endif - + - Return H_Success. + If “flags” indicate HPT/SLB mode (flags[61-62] is 0b00) then set + LPCR[UPRT] to FALSE else set LPCR[UPRT] to TRUE - + + + + + Input parameters: + + The “flags” parameter communicates the desired operation. The “base” + parameter specifies the VSID number of a one terabyte segment (right + justified in the register). The “page_size” parameter specifies the size + of the pages within the table encoded as per the L||LP encoding used by the + HPT hcalls that is presented in the page size info in the device tree. The + “table_size” parameter specifies the total size of the process table encoded + as the integer (log2 (total table length in bytes)) – 12 (table_size <= 24).
-
- Logical Partition Control Modes - Selected logical partition control modes may be modified by the - client program. - -
- Secondary Page Table Entry Group (PTEG) Search - The page table search algorithm, described by the - , consists of searching for a - Page Table Entry (PTE) in up to two PTEGs. The first PTEG searched is the - “primary PTEG”. If a PTE match does not occur in the primary - PTEG, the hardware may search the “secondary PTEG”. If a PTE - match is not found in the searched PTEGs, the hardware signals a - translation exception. - Code is not required to place any PTEs in secondary PTEGs. - Therefore, if a PTE match does not occur in a primary PTEG there is no - need for the hardware to search a secondary PTEG to determine that a - search has failed. The “Secondary Page Table Entry Group” bit - of - “ibm,client-architecture-support” allows - code to indicate that there is no need to search secondary PTEGs to - determine that a PTE search has failed. -
-
-
Partition Energy Management Option (PEM) This section describes the functional interfaces that are available @@ -17198,98 +18825,474 @@ hcall ( const uint64 H_VPM_PSTAT /* Returns the memory pool performance statisti . The hypervisor is then free to take energy management actions with this hint in mind. - - - R1--1. - - For the PEM option: The platform must honor the OS - set cede latency specifier value per the definition of - . - - - - - R1--2. - - For the PEM option: The platform must map any OS set - cede latency specifier value into one of its implemented values that does - not exceed the latency class set by the OS. - - - - - R1--3. - - For the PEM option: The platform must implement the - cede latency specifier values of 0 and 1 per - . - - - - - R1--4. + + + R1--1. + + For the PEM option: The platform must honor the OS + set cede latency specifier value per the definition of + . + + + + + R1--2. + + For the PEM option: The platform must map any OS set + cede latency specifier value into one of its implemented values that does + not exceed the latency class set by the OS. + + + + + R1--3. + + For the PEM option: The platform must implement the + cede latency specifier values of 0 and 1 per + . + + + + + R1--4. + + For the PEM option: If the platform implements cede + latency specifier values greater than 1 it must implement the cede + latency settings values sequentially without holes. + + + + + R1--5. + + For the PEM option: If the platform implements cede + latency specifier values greater than 1 each sequential cede latency + settings value must represent a cede wake up latency not less than its + predecessor, and no less restrictive than its predecessor. + + + + + R1--6. + + For the PEM option: If the platform implements cede + latency specifier values greater than 1 it must implement the cede + latency settings system parameter see + . + + + +
+ +
+ H_GET_EM_PARMS + This hcall() returns the partition’s energy management + parameters. The return parameters are packed into registers. + Programming Note: On platforms that implement the + partition migration option, after partition migration: + + + + The support for this hcall() might change, the caller should be + prepared to receive an H_Function return code indicating the platform + does not implement this hcall(). + + + + Fields that were defined as “reserved” might contain + data; calling code should be tested to ensure that it ignores fields + defined as “reserved” at the time of its design, and that it + operates properly when encountering “zeroed” defined fields + that indicate that the field does not contain useful data. + + + + + Implementation Note: To aid the testing of calling + code, implementations would do well to include debug tools that seed + reserved return fields with random data. + + + Syntax: + + + + + + + Parameters: (on return) + + + + + + + + + + + +   + + + + + + + + + + + + + + Status Codes (bit offset within 2 byte field): Bits 0:5 Reserved + (zero) + + + + Bits 6:8 Energy Management major code: + + + + 0b000: Non - floor modes: + + + + Bits 9:15 Energy Management minor code: + + + + + 0x00: The energy management policy for this aggregation level is + not specified. + + + + 0x01: Maximum Performance (Energy Management enabled - + performance may exceed nominal) + + + + 0x02: Nominal Performance (Energy Management Disabled) + + + + 0x03: Static Power Saving Mode + + + + 0x04: Deterministic Performance (Energy Management enabled + - consistent performance on a given workload independent of + environmental factors and component variances) + + + + 0x05 - 0x7F Reserved + + + + + + + + 0b001: Dynamic Power Management: + + + + Bits 9:15 Performance floor as a percentage of nominal (0% - + 100%). + + + + + + 0b010:0b111 Reserved + + + + + + Implementation Note: Status Code Fields are + determined by means outside the scope of LoPAR. Platform designs may + define a hierarchy of aggregations in which lower levels by default + inherit the energy management policy of their parent. + + + + + + + + + + + + + + + Bytes 0:3 four byte Power Draw Status/Limit for the + platform + + - For the PEM option: If the platform implements cede - latency specifier values greater than 1 it must implement the cede - latency settings values sequentially without holes. + Bit 0: Power Draw Limit is hard/soft: 0 = Soft, 1 = Hard - - - - R1--5. + - For the PEM option: If the platform implements cede - latency specifier values greater than 1 each sequential cede latency - settings value must represent a cede wake up latency not less than its - predecessor, and no less restrictive than its predecessor. + Bits 1:7 Reserved. - - - - R1--6. + - For the PEM option: If the platform implements cede - latency specifier values greater than 1 it must implement the cede - latency settings system parameter see - . + Bits 8:31 unsigned binary Power Draw Limit times 0.1 watts - - -
- -
- H_GET_EM_PARMS - This hcall() returns the partition’s energy management - parameters. The return parameters are packed into registers. - Programming Note: On platforms that implement the - partition migration option, after partition migration: + + + + + + + + + + + + + + +   + + + + + + + + + + - + - The support for this hcall() might change, the caller should be - prepared to receive an H_Function return code indicating the platform - does not implement this hcall(). + The total processor energy consumed by the calling partition + since boot in Joules times 2**-16. The value zero indicates that the + platform does not support reporting this parameter. + + + + + + + + + + + + + + + + + The total memory energy consumed by the calling partition since + boot in Joules times 2**-16. The value zero indicates that the platform + does not support reporting this parameter. + + + + + + + + + + + + + - Fields that were defined as “reserved” might contain - data; calling code should be tested to ensure that it ignores fields - defined as “reserved” at the time of its design, and that it - operates properly when encountering “zeroed” defined fields - that indicate that the field does not contain useful data. + The total I/O energy consumed by the calling partition since boot + in Joules times 2**-16. The value zero indicates that the platform does + not support reporting this parameter. - - + + + + + Semantics: + + + + Place the partition’s performance parameters for the + calling virtual processor’s partition into the respective + registers: - Implementation Note: To aid the testing of calling - code, implementations would do well to include debug tools that seed - reserved return fields with random data. + + + R4: Energy Management Status Codes + + + + R5: Power Draw Limits (Platform and Group) + + + + R6: Power Draw Limits (Pool and Partition) + + + + R7: Partition Processor Energy Consumption + + + + R8: Partition Memory Energy Consumption + + + + R9: Partition I/O Energy Consumption + + + + + + Return H_Success. + + + + + + R1--1. + + For the PEM option: The platform must implement the + H_GET_EMP hcall() following the syntax and semantics of + . + + + + +
+ +
+ H_BEST_ENERGY + This hcall() returns a hint to the caller as to the probable impact + toward the goal of minimal platform energy consumption for a given level + of computing capacity that would result from releasing or activating + various computing resources. The returned value is a unitless priority, + the lower the returned value; the more likely the goal will be achieved. + The accuracy of the returned hint is implementation dependent, and is + subject to change based upon actions of other partitions; thus the + implementation can only provide a “best effort” to be + “substantially correct”. Implementation dependent support for + this hcall() and supported resource codes might change during partition + suspension as in partition hibernation or migration; the client program + should be coded to gracefully handle H_Function, H_UNSUPPORTED, and + H_UNSUPPORTED_FLAG return codes. + H_BEST_ENERGY may be used in one of two modes, + “inquiry” or “ordered” specified by the setting + of bit 54 of the eflags parameter. It is intended that ordered mode be + used when the client program is largely indifferent to the specific + resource instance to be released or activated. In ordered mode, + H_BEST_ENERGY returns a list of resource instances in the order from the + best toward worst to choose to release/activate to achieve minimal energy + consumption starting with an initial resource instance in the ordered + list (if the specified initial resource is the reserved value zero the + returned list starts with the resource having the greatest probability of + minimizing energy consumption). It is intended that inquiry mode be used + when the client program wishes to compare the energy advantage of making + a resource selection from among a set of candidate resource instances. In + inquiry mode, H_BEST_ENERGY returns the unitless priority of + releasing/acquiring each of the specified resource instances. It is + expected that in the vast majority of cases, the client code will receive + data on a sufficient number of resource instances in one H_BEST_ENERGY + call to make its activate/release decision; however, in those rare cases + where more information is needed, a series of H_BEST_ENERGY calls can be + made to accumulate information on an arbitrary number of computing + resource instances. + Platforms may optionally support “buffered ordered” + return data mode. If the platform supports “buffered ordered” + return data mode, a “b” suffix appears at the end of the list + that terminates the hcall-best-energy-1 function set entry. If the + “buffered ordered” return data mode is supported the caller + may specify the “B” bit in the eflags parameter and supply in + P3 the logical address of a 4K byte aligned return buffer. + The probable effects of a given resource instance selection might + vary depending upon the intention of the client program to take other + actions. These other actions include the ability to reactivate a released + resource within a given time latency and number of resources the client + program intends to activate/release as a group. The eflags parameter to + H_BEST_ENERGY contains fields that convey hints to the platform of the + client program intentions in these areas; implementations might take + these hints into consideration as appropriate. The high order four (4) + bytes of the eflags parameter contain the unsigned required reactivation + latency in time base ticks (the reserved value of all zeros indicates an + unspecified reactivation latency). + Calling H_BEST_ENERGY with the eflags “refresh” flag + (bit 54) equal to a one causes the hypervisor to compute the relative + unitless priority value (1 being the best to activate/release with + increasing numbers being poorer choices from the perspective of potential + energy savings) for each instance of the specified resource that is owned + by the calling partition. If the hypervisor can not distinguish a + substantially different estimate for the various resource instances the + call returns H_Not_Available. If the “refresh” flag is equal + to a zero, the list as previously computed is used. Care should be + exercised when using the non-refresh version to ensure that the state of + the partition’s owned resource list has been initialized at some + point and has not changed due to resource instance activation/release + (including dynamic reconfiguration) activities by other partition threads + else the results of the H_BEST_ENERGY call are unpredictable (ranging + from inaccurate prediction values up to and including error code + responses). + The return values for H_BEST_ENERGY are passed in registers. + Following standard convention, the return code is in R3. Register R4 + contains the response count. If the call is made in “inquiry” + mode the response count equals the number of non-zero requested resource + instance entries in the call. If the call is made in + “ordered” mode, the response count contains the number of + entries in the ordered list from the first entry returned until the worst + choice entry. If the response count is <= 8 (512 for ordered buffer + mode) then the response count also indicates how many resource instances + are being reported by this call, if the response count is >8 (512 for + ordered buffer mode) then this call reports eight (512 for ordered buffer + mode) resource instances. Each response consists of three fields: bytes 0 + -- 2 are reserved, byte 3 contains the unitless priority for selecting + the indicated resource instance, and bytes 4 -- 7 contain the resource + instance identifier value corresponding to that passed in the + “ibm,my-drc-index” property. + In order to represent more accurately the significance of certain + priority values relative to others, the platform might leave holes in the + ranges of reported priority values. As an example there may be a gap of + several priority numbers between the value associated with a resource + that can be powered down versus one that can only be placed in an + intermediate energy mode, and yet again another gap to a resource that + represents a necessary but not sufficient condition for reducing energy + consumption. Syntax: @@ -17297,23 +19300,56 @@ hcall ( const uint64 H_VPM_PSTAT /* Returns the memory pool performance statisti + /* H_Function: The hcall() is not supported */ + /* H_Busy: The hcall() is not complete call again */ + /* H_Not_Available: Differentiated energy estimates are not */ + /* available for this resource */ + /* H_UNSUPPORTED_FLAG: Unsupported eflags parameter bits */ + /* (32 -- 39 & 48 -- 56) */ + /* H_UNSUPPORTED: The specified resource code is not */ + /* supported by this implementation */ + /* H_P2 -- H_P9: Invalid resource identifier value for the */ + /* calling partition */ +hcall ( uconst64 H_BEST_ENERGY, + int64 eflags, /* Bits 0 -- 31 Required wakeup latency in time base ticks. */ + /* Bits 32 -- 39 Reserved for expansion */ + /* Bits 40 -- 47 1 Byte count of the number of resources */ + /* that the caller intends to activate / release */ + /* Bits 48 -- 51 Reserved for expansion */ + /* Bit 52 = 0b0 return in registers = 0b1 ordered buffer */ + /* mode */ + /* Bit 53 = 0b0 use established list = 0b1 refresh list */ + /* Bit 54 = 0b0 inquiry; = 0b1 ordered */ + /* Bit 55 = 0b0 release; = 0b1 activate resource */ + /* Bits 56 -- 63 resource code: */ + /* 0 Reserved */ + /* 1 Processor */ + /* 2 Memory LMB */ + int64 P2, /* The parameters P2 -- P9 are all the same format, */ + /* except in ordered buffer mode when P3 contains the */ + /* logical address of a 4K byte aligned caller partition */ + /* memory buffer. */ + int64 P3, /* On input they contain either the reserved value of zero */ + int64 P4, /* or the resource instance identifier value as reported */ + int64 P5, /* in the “ibm,my-drc-index” property. */ + int64 P6, /* In “inquiry” mode they list resource instances */ + int64 P7, /* queried; from the contents of P2 up to the first */ + int64 P8, /* parameter containing all zeros – from there on to P9 */ + int64 P9 ); /* all the rest are ignored. */]]> - Parameters: (on return) + Parameters: (on entry) - - @@ -17322,1256 +19358,2241 @@ hcall ( const uint64 H_GET_EM_PARMS /* Returns in R4 – R9 the Platform Energy - - + + + +   + + + + + + + + + + + (on return) + + + R3: Return code + + + R4: Response Count Value <8 indicate the number of returned + values in registers starting with R5. The contents of registers after the + last returned value as indicated by the Response Count Value are + undefined. + + + R5 -- R12 Bytes 0-2 Reserved + + + Byte 3: 1 - 255 -- unitless priority value relative to + lowest total energy consumption for selecting the corresponding resource + ID. + + + Bytes 4-7 Resource instance ID to be used as input to dynamic + reconfiguration RTAS calls as would the value presented in the + “ibm,my-drc-index” property. + + + + + + Semantics: + + + + If the resource code in the eflags parameter is not supported + return H_UNSUPPORTED + + + + If other binary eflags values are not valid then return + H_UNSUPPORTED_FLAG with the specific value being (-256 - the bit + position of the highest order unsupported bit that is a one); + + + + If the eflags parameter “refresh” bit is zero and the + list has not been refreshed since the last return of H_Not_Available then + return H_Not_Available. + + + + If the eflags parameter “refresh” bit is a one + then: + + + + If energy estimates for the partition owned resources are + substantially indistinguishable then return H_Not_Available. + + + + Assign a priority value to each resource of the type specified in + the resource code owned by the calling partition relative to the probable + effect that selecting the specified resource to activate/release (per + eflags code) within the specified latency requirements would have on + achieving minimal platform energy consumption. (1 being the best + increasing values being worse - implementations may choose to use + an implementation dependent subset of the available values) + + + + Order the specified resources owned by the calling partition + starting with those having a priority value of 1; setting the resource + pointer to reference that starting resource. + + + + + + If the eflags parameter bit 54 is a one (“ordered”) + then + + + + If P2 == 0 then set pointer to best resource in ordered + list + + + + Else + + + + If P2 <> the drc-index of one of the resources in the + ordered list then return H_P2 + + + + Else set pointer to the resource corresponding to P2 + + + + + + Set R4 to the number of resources in the ordered list from the + pointer to the end + + + + If eflags “B” bit == 0b0 then /* this assumes that + the ordered buffer option is supported */: + + + + If R4 > 8 set count to 8 else set count to R4 + + + + Load “count” registers starting with R5 with the + priority value and resource IDs of the “count” resource + instances from the ordered list starting with the resource instance + referenced by “pointer”. + + + + + + Else - - - Status Codes (bit offset within 2 byte field): Bits 0:5 Reserved - (zero) + + + If P3 does not contain the 4K aligned logical address of a + calling partition memory page then return H_P3 + + + + If R4 > 512 set count to 512 else set count to R4 + + + + Load “count” 8 byte memory fields starting with + logical address in R3 with the priority value and resource IDs of the + “count” resource instances from the ordered list starting + with the resource instance referenced by “pointer”. + + + + + + Return H_SUCCESS + + - Bits 6:8 Energy Management major code: + Else /* “inquiry” mode */ - 0b000: Non - floor modes: - + Set R4 to zero + + + + For each input parameter P2 -- P9 or until the input parameter is + zero + - Bits 9:15 Energy Management minor code: + If the input parameter Px <> the drc-index of one of the + resources in the ordered list then return H_Px + + + + Fill in byte 3 of the register containing Px with the priority + value of the resource instance corresponding to the drc-index (bytes 4 -- + 7) of the register. + + + + Increment R4 + + + + + + Return H_SUCCESS + + + + - - - - 0x00: The energy management policy for this aggregation level is - not specified. - + + + R1--1. + + For the PEM option: The platform must implement the + H_BEST_ENERGY hcall() following the syntax and semantics of + . + + + + +
+
+ +
+ Platform Facilities + This section documents the hypervisor interfaces to optional platform + facilities such as special purpose coprocessors. + +
+ H_RANDOM + If the platform supports a random number generator platform + facility the + “ibm,hypertasfunctions” property of the + /rtas node contains the function set specification + “hcall-random” and the following hcall() is supported. - - 0x01: Maximum Performance (Energy Management enabled - - performance may exceed nominal) - + + Syntax: + + +
+ +
+ Co-Processor Facilities + If the platform supports a co-processor platform facility the + “ibm,hypertas-functions” property of the + /rtas node contains + the function set specification “hcall-cop” and the following + hcall()s are supported. + For asynchronous coprocessor operations the caller may either + specify an interrupt source number to signal at completion or the caller + may poll the completion code in the CSB. The hypervisor and caller need + to take into account the processor storage models with explicit memory + synchronization to ensure that the rest of the return data from the + operation is visible prior to setting the CSB completion code, and that + any operation data that might have been fetched prior to the setting of + the CSB completion code is discarded. + Note: The H_MIGRATE_DMA hcall() does not handle data pages subject + to co-processor access, it is the caller’s responsibility to make + sure that outstanding co-processor operations do not target pages that + are being migrated by H_MIGRATE_DMA. + +
+ H_COP_OP + The architectural intent of this hcall() is to initiate a + co-processor operation. Co-processor operations may complete with either + synchronous or asynchronous notification. In synchronous notification, + all platform resources associated with the operation are allocated and + released between the call to H_COP_OP and the subsequent return. In + asynchronous notification, operation associated platform resources may + remain allocated after the return from H_COP_OP, but are subsequently + recovered prior to setting the completion code in the CSB. For the + partition migration option no asynchronous notification operation may be + outstanding at the time the partition is suspended. - - 0x02: Nominal Performance (Energy Management Disabled) - + + Syntax: + + - - 0x03: Static Power Saving Mode - + + Syntax: - - 0x04: Deterministic Performance (Energy Management enabled - - consistent performance on a given workload independent of - environmental factors and component variances) - + + + Flags: + + + + Reserved (bits 0-- 38) + + + + “Rc” (bit 39) On Asymmetric Encryption operations the + “Rc” bit indicates that the high order 16 bits of the + “in” parameter contain the “Rc” field specifying + the encoded operand length while the remainder of the “in” + and “inlen” parameter bits are reserved and should be + 0b0 + + + + Notification of Operation (bits 40-- 41): + + + + 00 Synchronous: In this mode the hypervisor synchronously waits + for the coprocessor operation to complete. To preserve Interrupt service + times of the caller and quality of service for other callers, the length + of synchronous operations is restricted (see inlen parameter). + + + + 01 Reserved + + + + 10 Asynchronous: In this mode the hypervisor starts the + coprocessor operation and returns to the caller. The caller may poll for + operation completion in the CSB. + + + + 11 Async Notify: In this mode the hypervisor starts the + coprocessor operation as with the Asynchronous notification above however + the operation is flagged to generate a completion interrupt to the + interrupt source number given in the + “ibm,copint” property. When the interrupt + is signaled the caller may check the operation completion status in the + CSB. + + + + + + Interrupt descriptor index for Async Notify (bits 42-- 55) + + + + FC field: The FC field is the co-processor name specific function + code (bits 56-- 63) + + + + + + Resource identifier (bits 32-- 63(as from the + “ibm,resource-id” property)) - - 0x05 - 0x7F Reserved - - - - - - - - 0b001: Dynamic Power Management: - - - - Bits 9:15 Performance floor as a percentage of nominal (0% - - 100%). - - - - - - 0b010:0b111 Reserved - - - - + + + in/inlen and out/outlen parameters: + + + + If the *len parameter is non-negative; the respective in/out + parameter is the logical real address of the start of the respective + buffer. The starting address plus the associated length may not extend + beyond the bounds of a 4K page owned by the calling partition. For + synchronous notification operations, the parameter values may not exceed + an implementation specified maximum; in some cases these are communicated + by the values of the + “ibm,maxsync-cop” property of the device + tree node that represents the co-processor to the partition. + + + + If the *len parameter is negative; the respective in/out + parameter is the logical real address of the start of a scatter/gather + list that describes the buffer with a length equal to the absolute value + of the *len parameter. The starting address of the scatter/gather list + plus the associated length may not extend beyond the bounds of a 4K page + owned by the calling partition. Further the scatter/gather list shall be + a multiple of 16 bytes in length not to exceed the value of the + “ibm,max-sg-len” property of the device tree + node that represents the coprocessor to the partition. Each 16 byte entry + in the scatter gather list consists of an 8 byte logical real address of + the start of the respective buffer segment. The starting address plus the + associated length may not extend beyond the bounds of a 4K page owned by + the calling partition. For synchronous notification operations, the + summation of the buffer segment lengths for the in scatter/gather list + may be limited; in some cases these limitations are communicated by the + value of the + “ibm,max-sync-cop” property of the device + tree node that represents the coprocessor to the partition. + + + - Implementation Note: Status Code Fields are - determined by means outside the scope of LoPAR. Platform designs may - define a hierarchy of aggregations in which lower levels by default - inherit the energy management policy of their parent. + + csbcpb: logical real address of the 4K naturally aligned memory + block used to house the co-processor status block and FC field dependent + co-processor parameter block. + + + + Output parameters on return - - - - - - - - - - + + + R3 contains the standard hcall() return code: if the return code + is H_Success then the contents of the 4K naturally aligned page specified + by the csbspb parameter are filled from the hypervisor csb and cpb with + addresses converted from real to calling partition logical real + + + + + - - - Bytes 0:3 four byte Power Draw Status/Limit for the - platform + + Semantics: - Bit 0: Power Draw Limit is hard/soft: 0 = Soft, 1 = Hard + The hypervisor checks that the resource identifier parameter is + valid for the calling partition else returns H_RH_PARM. - Bits 1:7 Reserved. + The hypervisor checks that for the coprocessor type specified by + the validated resource identifier parameter there are no non-zero + reserved bits within the function expansion field of the flags parameter + else returns H_UNSUPPORTED_FLAG for the highest order non-zero + unsupported flag. - Bits 8:31 unsigned binary Power Draw Limit times 0.1 watts + If the operation notification is asynchronous, check that there + are sufficient resources to initiate and track the operation else return + H_Resource. - - - - - - - - - - - - - - -   - - - - - - - - - - + + + The hypervisor checks that the flag parameter notification field + is not a reserved value and FC field is valid for the specified + coprocessor type else returns H_ST_PARM + + + + If the notification field is “synchronous” the + hypervisor checks that the FC field is valid for synchronous operations + else return H_OP_MODE. + + + + The hypervisor builds the CRB CCW field per the coprocessor type + specified by the validated resource identifier parameter and by copying + the coprocessor type defined number of FC field bits from the low order + flags parameter FC field to the corresponding low order bits of CCW byte + 3. + + + + If the resource ID is an asymmetric encryption then (If the Flags + Parameter “Rc” bit is on then check the High order 16 bits of + the “in” parameter for a valid “Rc” encoding and + transfer to the CRB starting at byte 16 else return H_P2) else Validate + the inlen/in parameters and build the source DDE - - - The total processor energy consumed by the calling partition - since boot in Joules times 2**-16. The value zero indicates that the - platform does not support reporting this parameter. - - + + + Verify that the “in” parameter represents a valid + logical real address within the caller’s partition else return + H_P2 + + + + If the “inlen” parameter is non-negative: - - - - - - - - - - + + + Verify that the logical real address of (in + inlen) is a valid + logical real address within the same 4K page as the “in” + parameter else return H_P3. + + + + If the operation notification is synchronous verify that the + combination of parameter values request a sufficiently short operation + for synchronous operation else return H_TOO_BIG. + + + + + + If the “inlen” parameter is negative: - - - The total memory energy consumed by the calling partition since - boot in Joules times 2**-16. The value zero indicates that the platform - does not support reporting this parameter. - - + + + Verify that the absolute value of inlen meet all of the follow + else return H_P3: + + + + Is <= the value of + “ibm,max-sg-len” + + + + Is an even multiple of 16 + + + + That in + the absolute value of inlen represents a valid logical + real address within the same 4K caller partition page as the in + parameter. + + + + + + Verify that each 16 byte scatter gather list entry meets all of + the following else return H_SG_LIST: - - - - - - - - - - + + + Verify that the first 8 bytes represents a valid logical real + address within the caller’s partition. + + + + Verify that the logical real address represented by the sum of + the first 8 bytes and the second 8 bytes is a valid logical real address + within the same 4K byte page as the first 8 bytes. + + + + + + If the operation notification is synchronous verify that the sum + of all the scatter gather length fields (second 8 bytes of each 16 byte + entry) request a sufficiently short operation for synchronous operation + else return H_TOO_BIG. + + + + + + For the Shared Logical Resource Option if any of the memory + represented by the in/inlen parameters have been rescinded then return + H_RESCINDED. + + + + Fill in the source DDE list from the converted the in/inlen + parameters. + + + + + + Validate the outlen/out parameters and build the target + DDE - - - The total I/O energy consumed by the calling partition since boot - in Joules times 2**-16. The value zero indicates that the platform does - not support reporting this parameter. - - - - - - Semantics: - - - - Place the partition’s performance parameters for the - calling virtual processor’s partition into the respective - registers: + + + Verify that the “out” parameter represents a valid + logical real address within the caller’s partition else return + H_P4 + + + + If the “outlen” parameter is non-negative verify that + the logical real address of (out + outlen) is a valid logical real + address within the same 4K page as the “out” parameter + and for symmetric cryptography operations that outlen => inlen else + return H_P5. + + + + If the “outlen” parameter is negative: - - - R4: Energy Management Status Codes - - - - R5: Power Draw Limits (Platform and Group) - - - - R6: Power Draw Limits (Pool and Partition) - - - - R7: Partition Processor Energy Consumption - - - - R8: Partition Memory Energy Consumption - - - - R9: Partition I/O Energy Consumption - - - - - - Return H_Success. - - + + + Verify that the absolute value of outlen meet all of the follow + else return H_P5: - - - R1--1. - - For the PEM option: The platform must implement the - H_GET_EMP hcall() following the syntax and semantics of - . - - - - -
- -
- H_BEST_ENERGY - This hcall() returns a hint to the caller as to the probable impact - toward the goal of minimal platform energy consumption for a given level - of computing capacity that would result from releasing or activating - various computing resources. The returned value is a unitless priority, - the lower the returned value; the more likely the goal will be achieved. - The accuracy of the returned hint is implementation dependent, and is - subject to change based upon actions of other partitions; thus the - implementation can only provide a “best effort” to be - “substantially correct”. Implementation dependent support for - this hcall() and supported resource codes might change during partition - suspension as in partition hibernation or migration; the client program - should be coded to gracefully handle H_Function, H_UNSUPPORTED, and - H_UNSUPPORTED_FLAG return codes. - H_BEST_ENERGY may be used in one of two modes, - “inquiry” or “ordered” specified by the setting - of bit 54 of the eflags parameter. It is intended that ordered mode be - used when the client program is largely indifferent to the specific - resource instance to be released or activated. In ordered mode, - H_BEST_ENERGY returns a list of resource instances in the order from the - best toward worst to choose to release/activate to achieve minimal energy - consumption starting with an initial resource instance in the ordered - list (if the specified initial resource is the reserved value zero the - returned list starts with the resource having the greatest probability of - minimizing energy consumption). It is intended that inquiry mode be used - when the client program wishes to compare the energy advantage of making - a resource selection from among a set of candidate resource instances. In - inquiry mode, H_BEST_ENERGY returns the unitless priority of - releasing/acquiring each of the specified resource instances. It is - expected that in the vast majority of cases, the client code will receive - data on a sufficient number of resource instances in one H_BEST_ENERGY - call to make its activate/release decision; however, in those rare cases - where more information is needed, a series of H_BEST_ENERGY calls can be - made to accumulate information on an arbitrary number of computing - resource instances. - Platforms may optionally support “buffered ordered” - return data mode. If the platform supports “buffered ordered” - return data mode, a “b” suffix appears at the end of the list - that terminates the hcall-best-energy-1 function set entry. If the - “buffered ordered” return data mode is supported the caller - may specify the “B” bit in the eflags parameter and supply in - P3 the logical address of a 4K byte aligned return buffer. - The probable effects of a given resource instance selection might - vary depending upon the intention of the client program to take other - actions. These other actions include the ability to reactivate a released - resource within a given time latency and number of resources the client - program intends to activate/release as a group. The eflags parameter to - H_BEST_ENERGY contains fields that convey hints to the platform of the - client program intentions in these areas; implementations might take - these hints into consideration as appropriate. The high order four (4) - bytes of the eflags parameter contain the unsigned required reactivation - latency in time base ticks (the reserved value of all zeros indicates an - unspecified reactivation latency). - Calling H_BEST_ENERGY with the eflags “refresh” flag - (bit 54) equal to a one causes the hypervisor to compute the relative - unitless priority value (1 being the best to activate/release with - increasing numbers being poorer choices from the perspective of potential - energy savings) for each instance of the specified resource that is owned - by the calling partition. If the hypervisor can not distinguish a - substantially different estimate for the various resource instances the - call returns H_Not_Available. If the “refresh” flag is equal - to a zero, the list as previously computed is used. Care should be - exercised when using the non-refresh version to ensure that the state of - the partition’s owned resource list has been initialized at some - point and has not changed due to resource instance activation/release - (including dynamic reconfiguration) activities by other partition threads - else the results of the H_BEST_ENERGY call are unpredictable (ranging - from inaccurate prediction values up to and including error code - responses). - The return values for H_BEST_ENERGY are passed in registers. - Following standard convention, the return code is in R3. Register R4 - contains the response count. If the call is made in “inquiry” - mode the response count equals the number of non-zero requested resource - instance entries in the call. If the call is made in - “ordered” mode, the response count contains the number of - entries in the ordered list from the first entry returned until the worst - choice entry. If the response count is <= 8 (512 for ordered buffer - mode) then the response count also indicates how many resource instances - are being reported by this call, if the response count is >8 (512 for - ordered buffer mode) then this call reports eight (512 for ordered buffer - mode) resource instances. Each response consists of three fields: bytes 0 - -- 2 are reserved, byte 3 contains the unitless priority for selecting - the indicated resource instance, and bytes 4 -- 7 contain the resource - instance identifier value corresponding to that passed in the - “ibm,my-drc-index” property. - In order to represent more accurately the significance of certain - priority values relative to others, the platform might leave holes in the - ranges of reported priority values. As an example there may be a gap of - several priority numbers between the value associated with a resource - that can be powered down versus one that can only be placed in an - intermediate energy mode, and yet again another gap to a resource that - represents a necessary but not sufficient condition for reducing energy - consumption. + + + Is <= the value of + “ibm,max-sg-len” + + + + Is an even multiple of 16 + + + + That out + the absolute value of outlen represents a valid + logical real address within the same 4K caller partition page as the out + parameter + + + + + + Verify that each 16 byte scatter gather list entry meets all of + the following else return H_SG_LIST: - - Syntax: + + + Verify that the first 8 bytes represents a valid logical real + address within the caller’s partition. + + + + Verify that the logical real address represented by the sum of + the first 8 bytes and the second 8 bytes is a valid logical real address + within the same 4K page as the first 8 bytes. + + + + Accumulate the sum of the second 8 bytes of each scatter gather list entry. + + + + + + Verify that for symmetric cryptography operations the accumulated sum + of the second 8 bytes of each scatter gather list entry =>the input data length + else return H_P5. + + + + + + For the Shared Logical Resource Option if any of the memory + represented by the out/outlen parameters have been rescinded then return + H_RESCINDED. + + + + Fill in the destination DDE list from the converted the + out/outlen parameters. + + + + + + If the operation notification is asynchronous then verify that + the input and output buffers do not overlap else return H_OVERLAP (makes + the operations transparently restartable) + + + + Check that the csbcpb parameter is page aligned within the + calling address space of the calling partition else return H_P6 + + + + If the operation specifies a CPB and the specified CPB is invalid + for the operation then return H_ST_PARM. + + + + Set the CRB CSB address field & C bit to indicate a valid + CCB + + + + If the operation notification is asynchronous notify, + then: - + + Check that the flags parameter interrupt index value is within + the defined range for the validated rid and is not currently in use for + another outstanding COP operation else return H_INTERRUPT. + + + + Set the CRB CM field to command a completion interrupt,. + + + + Set the job id field in the Co-processor Completion Block to + command the signaling via the interrupt source number contained the + interrupt specifier indicated by the interrupt index value. + + + + For the CMO option, if the number of entitlement granules pinned + for this operation causes the partition memory entitlement to be + exhausted then return H_NOT_ENOUGH_RESOURCES; else pin and record the + entitlement granules used by this operation, and increment the partition + consumed memory entitlement for the number of entitlement granules pinned + for this operation. + + + + + + Set the completion code field in the passed (via csbcpb + parameter) CSB to invalid (it is subsequently set to valid at the end of + the operation just after the rest of the contents of the 4k naturally + aligned page specified by the csbcpb parameter are filled). + + + + Issue icswx + + + + If busy response to icswx implementation dependent (may be null) + retry after backoff based upon some usage equality/priority mechanisms + else return H_Busy. + + + + If the operation notification is asynchronous then Return + H_Success + + + + Wait for completion posting in CSB (CSB valid bit. 1) + + + + The contents of the 4K naturally aligned page specified by the + csbcpb parameter are filled from the hypervisor csb and cpb with + addresses converted from real to calling partition logical real + + + + Return H_Success. + + + + +
+ +
+ H_STOP_COP_OP + The architectural intent of this hcall() is to terminate a + previously initiated co-processor operation. + + + Syntax: + +hcall ( const H_STOP_COP_OP, + uint64 flags, /* sub functions and modifiers: Bits 0-- 63 reserved */ + uint32 rid, /* identifier as from the “ibm,resource-id” property */ + uint64 csbcpb /* The logical real address of the 4k page aligned storage */ + /* block containing the CSB & optional FC field specific */ + /* CPB */ + );]]> + - - - - Parameters: (on entry) - - - - - - - - - - - -   - - - - - - - - - - -   - - - - - - - - - - - + + Semantics: + + + + Check the rid parameter for validity for the caller else return + H_RH_PARM + + + If any reserved flags parameter bits are non zero then return + H_Parameter. + + + Check the csbcpb parameter for pointing within the caller’s + partition and 4K aligned else return H_P3 + + + For the shared logical resource option if the csbcpb parameter + references a rescinded shared logical resource then return + H_RESCINDED + + + If the csbcpb parameter is not associated with an outstanding + coprocessor operation then return H_NOT_ACTIVE. + + + Send a kill operation to the coprocessor handling the outstanding + operation + + + Wait for the outstanding kill operation to complete. + + + For the CMO option, unpin any entitlement granules still pinned + for this operation and decrement the consumed partition memory + entitlement for the number of entitlement granules pinned for this + operation. + + + Return H_Success. + + + +
+
+ +
+ Memory Usage Instrumentation Option (MUI) - - (on return) - - - R3: Return code - - - R4: Response Count Value <8 indicate the number of returned - values in registers starting with R5. The contents of registers after the - last returned value as indicated by the Response Count Value are - undefined. - - - R5 -- R12 Bytes 0-2 Reserved - - - Byte 3: 1 - 255 -- unitless priority value relative to - lowest total energy consumption for selecting the corresponding resource - ID. - - - Bytes 4-7 Resource instance ID to be used as input to dynamic - reconfiguration RTAS calls as would the value presented in the - “ibm,my-drc-index” property. - - - + The MUI Option enables the platform to generate statistics on + page reference affinity, age, access rate, and + reference history pattern. Client programs can + query and act upon this information in order to guide + decisions for improving memory utilization and placement in a system. - - Semantics: + The MUI Option consists of a number of distinct per page measures + as described in . + +
+ Memory Usage Instrumentation Measures + + + + + + + + Name + - - - If the resource code in the eflags parameter is not supported - return H_UNSUPPORTED - - - - If other binary eflags values are not valid then return - H_UNSUPPORTED_FLAG with the specific value being (-256 - the bit - position of the highest order unsupported bit that is a one); - - - - If the eflags parameter “refresh” bit is zero and the - list has not been refreshed since the last return of H_Not_Available then - return H_Not_Available. - - - - If the eflags parameter “refresh” bit is a one - then: + + Abbreviation + - - - If energy estimates for the partition owned resources are - substantially indistinguishable then return H_Not_Available. - - - - Assign a priority value to each resource of the type specified in - the resource code owned by the calling partition relative to the probable - effect that selecting the specified resource to activate/release (per - eflags code) within the specified latency requirements would have on - achieving minimal platform energy consumption. (1 being the best - increasing values being worse - implementations may choose to use - an implementation dependent subset of the available values) - - - - Order the specified resources owned by the calling partition - starting with those having a priority value of 1; setting the resource - pointer to reference that starting resource. - - - - - - If the eflags parameter bit 54 is a one (“ordered”) - then + + Description + + + + + + + Reference History Bit Array + - - - If P2 == 0 then set pointer to best resource in ordered - list - - - - Else + + HBA + - - - If P2 <> the drc-index of one of the resources in the - ordered list then return H_P2 - - - - Else set pointer to the resource corresponding to P2 - - - - - - Set R4 to the number of resources in the ordered list from the - pointer to the end - - - - If eflags “B” bit == 0b0 then /* this assumes that - the ordered buffer option is supported */: + + Measures dormancy patterns – a list of bits each representing a time + interval, if the bit is a one the page was reference during the + corresponding interval. + + + + + Page Table Entry Update Time + - - - If R4 > 8 set count to 8 else set count to R4 - - - - Load “count” registers starting with R5 with the - priority value and resource IDs of the “count” resource - instances from the ordered list starting with the resource instance - referenced by “pointer”. - - - - - - Else + + PUT + - - - If P3 does not contain the 4K aligned logical address of a - calling partition memory page then return H_P3 - - - - If R4 > 512 set count to 512 else set count to R4 - - - - Load “count” 8 byte memory fields starting with - logical address in R3 with the priority value and resource IDs of the - “count” resource instances from the ordered list starting - with the resource instance referenced by “pointer”. - - - - - - Return H_SUCCESS - - - - - - Else /* “inquiry” mode */ + + The timestamp of the last HBA interval during which the + corresponding page experienced a TLB miss during a reference. + + + + + Access Count Array + - - - Set R4 to zero - - - - For each input parameter P2 -- P9 or until the input parameter is - zero + + ACA + - - - If the input parameter Px <> the drc-index of one of the - resources in the ordered list then return H_Px - - - - Fill in byte 3 of the register containing Px with the priority - value of the resource instance corresponding to the drc-index (bytes 4 -- - 7) of the register. - - - - Increment R4 - - - - - - Return H_SUCCESS - - - - + + The count of the corresponding page access used to compute page + access rate. + + + + + Page Age Counter + + + + PAC + + + + A saturating count representing the length of time since the page + statistics were reset. + + + + + Page Age Granule + - - - R1--1. - - For the PEM option: The platform must implement the - H_BEST_ENERGY hcall() following the syntax and semantics of - . - - - - - - - -
- Platform Facilities - This section documents the hypervisor interfaces to optional platform - facilities such as special purpose coprocessors. - -
- H_RANDOM - If the platform supports a random number generator platform - facility the - “ibm,hypertasfunctions” property of the - /rtas node contains the function set specification - “hcall-random” and the following hcall() is supported. + + PAG + - + + The update cycle period of the Page Age Counter in seconds. + + + + + Affinity Log Array + -
- -
- Co-Processor Facilities - If the platform supports a co-processor platform facility the - “ibm,hypertas-functions” property of the - /rtas node contains - the function set specification “hcall-cop” and the following - hcall()s are supported. - For asynchronous coprocessor operations the caller may either - specify an interrupt source number to signal at completion or the caller - may poll the completion code in the CSB. The hypervisor and caller need - to take into account the processor storage models with explicit memory - synchronization to ensure that the rest of the return data from the - operation is visible prior to setting the CSB completion code, and that - any operation data that might have been fetched prior to the setting of - the CSB completion code is discarded. - Note: The H_MIGRATE_DMA hcall() does not handle data pages subject - to co-processor access, it is the caller’s responsibility to make - sure that outstanding co-processor operations do not target pages that - are being migrated by H_MIGRATE_DMA. - -
- H_COP_OP: - The architectural intent of this hcall() is to initiate a - co-processor operation. Co-processor operations may complete with either - synchronous or asynchronous notification. In synchronous notification, - all platform resources associated with the operation are allocated and - released between the call to H_COP_OP and the subsequent return. In - asynchronous notification, operation associated platform resources may - remain allocated after the return from H_COP_OP, but are subsequently - recovered prior to setting the completion code in the CSB. For the - partition migration option no asynchronous notification operation may be - outstanding at the time the partition is suspended. + + ALA + - + + A sampled list of affinity domains that have accessed the page. + + + + + Affinity Log Sample Period + - - Syntax: + + ALSP + - + + The period that each Affinity Log Array entry represents in seconds. + + +
+ +
+ + Client programs monitor and manage the MUI state through the extensions to the H_ENTER + (see ), H_RETURN_PAGEINFO, H_MEMSTAT_CTRL, + H_RESET_MEMSTATS, and H_BULK_READ_HBA hcall()s. The data returned by the + H_RETURN_PAGEINFO and H_BULK_READ_HBA hcall()s generally reflect actual values. However, + should a logical page be faulted back into a partition when Active Memory Sharing (AMS) is in use, its + MUI state is cleared/set to a fixed value. MUI state is also subject to loss during events that move physical + memory such as: dynamic reconfiguration, partition mobility, and fail-over. + + bit for managing the MUI behavior of pages are detailed below in . + + + MUI Option Flags in Page Frame Table Access flags Detailed Description + + + + + + + + + Bit(s) + + + Name + + + Encoding + + + Description + + + + + + + 43:44 + + + Reference History Bit Array (HBA) + + + 0b00 + + + Disable HBA updates + + + + + 0b01 + + + Enable HBA updates, set PUT to previous time, but do + not change current HBA content (as in adding an alias to + a logical real page) + + + + + 0b10 + + + Enable HBA updates, set PUT to previous time, and set + the HBA to the configured Initial Setting. + + + + + 0b11 + + + Reserved – return H_UNSUPPORTED_FLAG + + + + + 45 + + + Affinity-Clear + + +   + + + Resets Affinity Log Array when entering a PTE. + + + + + 46 + + + Page-Age-Clear + + +   + + + Resets Page Age Counter when entering a PTE. + + + + +
+ + The parameters to Memory Usage Instrumentation hcall()s that specify a given logical page or page range + take the form of an index into the partition’s logical real memory space as if it were a set of 4K pages, the + logical page index being the logical real address of the starting byte of the 4K page, right shifted 12 bits. + + It is expected that the MUI function will evolve over time, as will the syntax of the MUI hcalls(). The + following requirements ensure forward compatibility over this expected evolution. + + + + R1--1. - Flags: - - - - Reserved (bits 0-- 38) - - - - “Rc” (bit 39) On Asymmetric Encryption operations the - “Rc” bit indicates that the high order 16 bits of the - “in” parameter contain the “Rc” field specifying - the encoded operand length while the remainder of the “in” - and “inlen” parameter bits are reserved and should be - 0b0 - - - - Notification of Operation (bits 40-- 41): + For the MUI option: + the platform must for all MUI hcall()s fill all reserved return parameter + registers with all zeros. + + + + + R1--2. + + For the MUI option: + to avoid future incompatibility, the caller of MUI hcall()s must ignore + the contents of all reserved return parameter registers. + + + + + R1--3. + + For the MUI option: + to avoid future incompatibility, the caller of MUI hcall()s must fill all + reserved input parameter fields with zeros. + + + - - - 00 Synchronous: In this mode the hypervisor synchronously waits - for the coprocessor operation to complete. To preserve Interrupt service - times of the caller and quality of service for other callers, the length - of synchronous operations is restricted (see inlen parameter). - - - - 01 Reserved - - - - 10 Asynchronous: In this mode the hypervisor starts the - coprocessor operation and returns to the caller. The caller may poll for - operation completion in the CSB. - - - - 11 Async Notify: In this mode the hypervisor starts the - coprocessor operation as with the Asynchronous notification above however - the operation is flagged to generate a completion interrupt to the - interrupt source number given in the - “ibm,copint” property. When the interrupt - is signaled the caller may check the operation completion status in the - CSB. - - - - - - Interrupt descriptor index for Async Notify (bits 42-- 55) - - +
+ H_MEMSTAT_CTRL + + This hcall() configures Memory Usage Instrumentation, and returns the current configuration. Note + supplying a value of all zeros returns the current configuration settings of the Memory Usage + Instrumentation facility. + + + Syntax: + + + + + Parameters: + + + + Input: + + - FC field: The FC field is the co-processor name specific function - code (bits 56-- 63) + R4: flags - + - Resource identifier (bits 32-- 63(as from the - “ibm,resource-id” property)) + Output: - + - in/inlen and out/outlen parameters: + R3: Return code - + - If the *len parameter is non-negative; the respective in/out - parameter is the logical real address of the start of the respective - buffer. The starting address plus the associated length may not extend - beyond the bounds of a 4K page owned by the calling partition. For - synchronous notification operations, the parameter values may not exceed - an implementation specified maximum; in some cases these are communicated - by the values of the - “ibm,maxsync-cop” property of the device - tree node that represents the co-processor to the partition. + R4: Config - + - If the *len parameter is negative; the respective in/out - parameter is the logical real address of the start of a scatter/gather - list that describes the buffer with a length equal to the absolute value - of the *len parameter. The starting address of the scatter/gather list - plus the associated length may not extend beyond the bounds of a 4K page - owned by the calling partition. Further the scatter/gather list shall be - a multiple of 16 bytes in length not to exceed the value of the - “ibm,max-sg-len” property of the device tree - node that represents the coprocessor to the partition. Each 16 byte entry - in the scatter gather list consists of an 8 byte logical real address of - the start of the respective buffer segment. The starting address plus the - associated length may not extend beyond the bounds of a 4K page owned by - the calling partition. For synchronous notification operations, the - summation of the buffer segment lengths for the in scatter/gather list - may be limited; in some cases these limitations are communicated by the - value of the - “ibm,max-sync-cop” property of the device - tree node that represents the coprocessor to the partition. + R5::R10: Reserved - + + + + + Memory Usage Instrumentation Configuration encoding flags/config + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +   + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + 21 + 22 + 23 + 24 + 25 + 26 + 27 + 28 + 29 + 30 + 31 + + + + + 0 + R + R + R + R + R + R + R + R + R + R + R + R + R + R + R + R + Flags = RRRRRRRR config = PAG + Flags = RRRRRRRR config = ALSP + + + 1 + R + R + R + R + R + R + R + R + R + R + R + R + ALA + ACA + HBA + R + R + Initial Setting + HUC + + + +
- - csbcpb: logical real address of the 4K naturally aligned memory - block used to house the co-processor status block and FC field dependent - co-processor parameter block. - - - - Output parameters on return + + Encoded values for Reference History Bit Array (HBA) (flags/config) + + + + + + + + Bit 0 + + + Bit 1 + + + Comment + + + + + + + 0 + + + 0 + + + No operationDo not change the HBA configuration or update cycle time, simply return + current settings. + + + + + 0 + + + 1 + + + Disable HBA updates + + + + + 1 + + + 0 + + + Enable an HBA update on the first TLB miss per HBA update cycle, and set the HBA per + the configured Initial Setting. (Note: If the platform does not support this setting, + H_MEMSTAT_CTRL returns H_RT_PARM, and the value of the HBA field in the + returned memory instrumentation configuration “out” parameter is 0b00.) + + + + + 1 + + + 1 + + + Enable an HBA update on the first access* per HBA update cycle and force a TLB miss + per HBA update cycle, and set the HBA per the configured Initial Setting. (Note: If the + platform does not support this setting, H_MEMSTAT_CTRL returns H_RT_PARM, and + the value of the HBA field in the returned memory instrumentation configuration “out” + parameter is 0b00.) + + + + +
+ + Implmentation Note: + This may be approximated by performing a TLBIA once per HBA update cycle; + thus forcing a TLB miss on the first subsequent page access. + + The Initial Setting field (flags/config): is a 6 bit field that defines the number of high order HBA bits that + are preloaded to a 1 when the HBA is initialized (for instance when the page is assigned a new virtual + address through H_ENTER). This field allows the software to bias the page statistics so that the page will + not be chosen as a victim before it can establish its own usage statistics. + + HBA Update Cycle Field (HUC) (flags/config): is a 6 bit field that defines the update cycle period in + microseconds multiplied by the power of two specified in the 6 bit field. The range of supported HUC + values is given in the “ibm,mui-ranges” + property. Note: If the platform does not support this setting, or + the supplied value, H_MEMSTAT_CTRL returns H_RT_PARM, and the value of the HUC field in the + returned memory instrumentation configuration “config” parameter is the reserved value 0b111111. + + + Encoded values for Access Count Array (ACA) (flags/config) + + + + + + + + Bit 0 + + + Bit 1 + + + Comment + + + + + + + 0 + + + 0 + + + No operationDo not change, simply return current setting of ACA configuration. + + + + + 0 + + + 1 + + + Disable ACA updatesNote: This setting will prevent the partition from seeing ACA + data, however, the platform may still accumulate such data for other purposes. + + + + + 1 + + + 0 + + + Enable ACA updatesNote: If the platform does not support this setting, H_MEMSTAT_CTRL returns + H_RT_PARM and the value of the ACA field in the returned memory instrumentation + configuration “config” parameter is 0b00. + On enable the platform is not required to initialize the counters except to preclude a covert + channel as in the case of page reassignment between partitions.) + + + + + 1 + + + 1 + + + Reserved:Note: If the caller supplies this value, H_MEMSTAT_CTRL returns + H_RT_PARM and the value of the ACA field in the returned memory instrumentation + configuration “config” parameter is 0b11. + + + + +
- - - R3 contains the standard hcall() return code: if the return code - is H_Success then the contents of the 4K naturally aligned page specified - by the csbspb parameter are filled from the hypervisor csb and cpb with - addresses converted from real to calling partition logical real - - - - + + Encoded values for Affinity Log Array (ALA) (flags/config) + + + + + + + + Bit 0 + + + Bit 1 + + + Comment + + + + + + + 0 + + + 0 + + + No operationDo not change, simply return current setting of ALA configuration + + + + + 0 + + + 1 + + + Disable ALA updatesNote: This setting will prevent the partition from seeing ALA data, + however, the platform may still accumulate such data for other purposes. + + + + + 1 + + + 0 + + + Enable ALA updatesNote: If the platform does not support this setting, + H_MEMSTAT_CTRL returns H_RT_PARM and the value of the ALA field in the + returned memory instrumentation configuration “config” parameter is 0b00. + On enable the platform is not required to initialize the counters except to preclude a covert + channel as in the case of page reassignment between partitions.) + + + + + 1 + + + 1 + + + Reserved:Note: If the caller supplies this value, H_MEMSTAT_CTRL returns + H_RT_PARM and the value of the ALA field in the returned memory instrumentation + configuration “config” parameter is 0b11. + + + + +
+ + The Page Age Granule (PAG) and Affinity Log Sample Period (ALSP) fields (config only): are 8 bit fields + that define these periods in seconds. Note: On input these are reserved fields, any value other than all + zeros causes H_MEMSTAT_CTRL to return H_UNSUPPORTED_FLAG. Semantics: - - - - The hypervisor checks that the resource identifier parameter is - valid for the calling partition else returns H_RH_PARM. - - - - The hypervisor checks that for the coprocessor type specified by - the validated resource identifier parameter there are no non-zero - reserved bits within the function expansion field of the flags parameter - else returns H_UNSUPPORTED_FLAG for the highest order non-zero - unsupported flag. - - - - If the operation notification is asynchronous, check that there - are sufficient resources to initiate and track the operation else return - H_Resource. - - + + - The hypervisor checks that the flag parameter notification field - is not a reserved value and FC field is valid for the specified - coprocessor type else returns H_ST_PARM + Returns H_UNSUPPORTED_FLAG if a “flags” parameter reserved bit is non-zero (contents of + R4 are undefined). - + - If the notification field is “synchronous” the - hypervisor checks that the FC field is valid for synchronous operations - else return H_OP_MODE. + Returns H_RT_PARM if a defined field of the “flags” parameter is either not supported or invalid + along with the current memory usage instrumentation configuration settings in register R4. - + - The hypervisor builds the CRB CCW field per the coprocessor type - specified by the validated resource identifier parameter and by copying - the coprocessor type defined number of FC field bits from the low order - flags parameter FC field to the corresponding low order bits of CCW byte - 3. + Otherwise sets requested memory usage instrumentation configuration, returns H_Success along + with the current memory usage instrumentation configuration settings in register R4. - - - If the resource ID is an asymmetric encryption then (If the Flags - Parameter “Rc” bit is on then check the High order 16 bits of - the “in” parameter for a valid “Rc” encoding and - transfer to the CRB starting at byte 16 else return H_P2) else Validate - the inlen/in parameters and build the source DDE + + +
- - - Verify that the “in” parameter represents a valid - logical real address within the caller’s partition else return - H_P2 - - - - If the “inlen” parameter is non-negative: +
+ H_RESET_MEMSTATS + + Resets page age, affinity log, and/or PUT/HBA for up to 6 logical real pages as specified by the logical + page index parameters. + + + Syntax: + + - - - Verify that the logical real address of (in + inlen) is a valid - logical real address within the same 4K page as the “in” - parameter else return H_P3. - - + + Parameters: + + + + Input: + + + flags: + - If the operation notification is synchronous verify that the - combination of parameter values request a sufficiently short operation - for synchronous operation else return H_TOO_BIG. + bits 0::60: Reserved - - - - - If the “inlen” parameter is negative: - - - Verify that the absolute value of inlen meet all of the follow - else return H_P3: - - - - Is <= the value of - “ibm,max-sg-len” - - - - Is an even multiple of 16 - - - - That in + the absolute value of inlen represents a valid logical - real address within the same 4K caller partition page as the in - parameter. - - + bit 61: HBA (History Bit Array): Set Bit Array to configured Initial Setting. - - Verify that each 16 byte scatter gather list entry meets all of - the following else return H_SG_LIST: - - - - Verify that the first 8 bytes represents a valid logical real - address within the caller’s partition. - - - - Verify that the logical real address represented by the sum of - the first 8 bytes and the second 8 bytes is a valid logical real address - within the same 4K byte page as the first 8 bytes. - - + bit 62: PAC (Page Age Counter) - - If the operation notification is synchronous verify that the sum - of all the scatter gather length fields (second 8 bytes of each 16 byte - entry) request a sufficiently short operation for synchronous operation - else return H_TOO_BIG. + bit 63: ALA (Affinity Log Array) - + - - - For the Shared Logical Resource Option if any of the memory - represented by the in/inlen parameters have been rescinded then return - H_RESCINDED. - - + - Fill in the source DDE list from the converted the in/inlen - parameters. + lpx1::lpx6: Logical page index(s) to be used - + - Validate the outlen/out parameters and build the target - DDE - - + Output: + - Verify that the “out” parameter represents a valid - logical real address within the caller’s partition else return - H_P4 + R3: Return code - - If the “outlen” parameter is non-negative verify that - the logical real address of (out + outlen) is a valid logical real - address within the same 4K page as the “out” parameter else - return H_P5. + R4::R10: Reserved - - - If the “outlen” parameter is negative: - - - - Verify that the absolute value of outlen meet all of the follow - else return H_P5: - - - - Is <= the value of - “ibm,max-sg-len” - - - - Is an even multiple of 16 - - - - That out + the absolute value of outlen represents a valid - logical real address within the same 4K caller partition page as the out - parameter - - - - - - Verify that each 16 byte scatter gather list entry meets all of - the following else return H_SG_LIST: + + + + - - - Verify that the first 8 bytes represents a valid logical real - address within the caller’s partition. - - - - Verify that the logical real address represented by the sum of - the first 8 bytes and the second 8 bytes is a valid logical real address - within the same 4K page as the first 8 bytes. - - - - - - - - For the Shared Logical Resource Option if any of the memory - represented by the out/outlen parameters have been rescinded then return - H_RESCINDED. - - - - Fill in the destination DDE list from the converted the - out/outlen parameters. - - + + Semantics: + + + + If (Flags AND HBA) and Reference History Bit Array not enabled, returns H_Not_Available. - - If the operation notification is asynchronous then verify that - the input and output buffers do not overlap else return H_OVERLAP (makes - the operations transparently restartable) + If (Flags AND ALA) and the Affinity Log Array not enabled, returns H_Not_Available. - - Check that the csbcpb parameter is page aligned within the - calling address space of the calling partition else return H_P6 + If (Flags AND PAA) and reference rate array not enabled, returns H_Not_Available. - - If the operation specifies a CPB and the specified CPB is invalid - for the operation then return H_ST_PARM. + If (Flags AND ACA) and reference rate array not enabled, returns H_Not_Available. - - Set the CRB CSB address field & C bit to indicate a valid - CCB + for each of lpx1..6 + Exits for each if lpx is FFFF_FFFF_FFFF_FFFF. + + If the lpx is not owned by the calling partition, return H_P(2..7) + If AMS mode and page is paged out move on as stats are reset on a page in + If (Flags AND ALA) + Reset the affinity log array for the lpx + If (Flags AND Page-Age) + Clear the page age counter for the lpx + If (Flags AND HBA) + Sets the configured Number of Ref Bits in the Reference History Bit Array for the lpx - - If the operation notification is asynchronous notify, - then: + Return H_Success. + + + +
- +
+ H_RETURN_PAGEINFO + + The H_RETURN_PAGEINFO hcall() returns the page usage information for a range of logical pages or a + list of specific logical pages. The results are returned in a 4K aligned buffer, the data for each logical page + occupying one 32 byte record, all other contents of the buffer are volatile and undefined. + + The range of logical pages is restricted to a single LMB boundary (the list of specific logical pages does not + have his restriction). If this restriction is violated, the H_RETURN_PAGEINFO hcall() returns H_P4. + + The RETURN of a page range might take longer than is allowable for a single call, or it might select more + pages than can be contained in the return buffer. Should either of these cases happen the + H_RETURN_PAGEINFO hcall() returns H_CONTINUE, along with the current results, and the value of + the lpx0 parameter for continuing the RETURN on a subsequent call from the termination point of the prior + call. + + The caller may specify a filter to further qualify the pages for which data is returned. For the CMO option + if the logical page has been paged out by the platform, the page is filtered out of the returned data. + + + Syntax: + + + + + Parameters: + + + + Input: + - Check that the flags parameter interrupt index value is within - the defined range for the validated rid and is not currently in use for - another outstanding COP operation else return H_INTERRUPT. + flags: + + H_MEMSTAT_CTRL Flag Layout + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +   + 0 + 1 + 2 + 3 + + + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + + + + + 0 + Ar + Accesses / Second + + + 1 + RESERVED + R + + + +
+ + + H_MEMSTAT_CTRL Flag Sub-field Layout + + + + + + + + + + Word + + + Byte + + + Bit + + + Name + + + Comment + + + + + + + 0 + + + 0 + + + 0-1 + + + Ar + + + Access Rate Filter Control + 0b00 Do not filter based upon Access Rate (ignore flags bits 2-31) + 0b01 Reserved (Returns H_Parameter if this condition value is set) + 0b10 Select if page access per second is greater than the value in bits 2::31. Note if the + specified value is greater than the MUI facilities’ maximum access rate capacity per the + “ibm,mui-ranges” + property this condition will not be met. + 0b11 Reserved (Returns H_Parameter if this condition value is set) + + + + + 2-7 + + + Accesses per second + + + + + 1-3 + + + All + + + + + 1 + + + 0-2 + + + All + + + Reserved + + + Reserved (Returns H_Parameter if this condition value is set) + + + + + 3 + + + 0-6 + + + + + 7 + + + R + + + 0: Returns page usage data for up to 5 pages specified one each in parameters + lpn0::lpn4 + 1: Returns page usage data for the range from the logical page in parameter lpn0 + through lpn1 + + + + +
- - Set the CRB CM field to command a completion interrupt,. + buffer: 4kB-aligned output buffer + Implementation Note: + This buffer is output only and may be initialized with dcbz + instructions to preclude memory error handling. - - Set the job id field in the Co-processor Completion Block to - command the signaling via the interrupt source number contained the - interrupt specifier indicated by the interrupt index value. + lpx0: The logical page number index for the first page. - - For the CMO option, if the number of entitlement granules pinned - for this operation causes the partition memory entitlement to be - exhausted then return H_NOT_ENOUGH_RESOURCES; else pin and record the - entitlement granules used by this operation, and increment the partition - consumed memory entitlement for the number of entitlement granules pinned - for this operation. + lpx1: For page Range option, the last logical page number index. For the list option, + and not the list terminator value (-1) continue to return page usage data for the + logical page number specified, else terminate the call. - + + lpx1::lpx4: For the list option, and not the list terminator value (-1) continue to return page + usage data for the logical page number specified, else terminate the call + + - Set the completion code field in the passed (via csbcpb - parameter) CSB to invalid (it is subsequently set to valid at the end of - the operation just after the rest of the contents of the 4k naturally - aligned page specified by the csbcpb parameter are filled). + Output: + + + R3: Return Code + + + R4: Number of matching entry records in destination buffer + + + R5: For the range RETURN option, if the return code is H_CONTINUE this value is + the value of the lpn0 parameter for a subsequent call to continue the RETURN. + + + R6::R10: Reserved + + - + + + + Buffer Record Format + + + + + + + + Field Name + + + Byte Offset + + + Description + + + + + + + lpx + + + 0::7 + + + The logical page number index of the selected page + + + + + access_rate + + + 8::15 + + + Accesses per second + + + + + affinity_log + + + 16::23 + + + Eight single byte integers. One integer for each of the past + eight ALSP intervals. The non-zero integer value + representing one of the masters that referenced the page + during the period. A zero value indicating that valid data is + not available for the represented period. The associativity list + for the referencing master is found in the + “ibm,muiassociativity-mapping” + property. + + + + + Reserved + + + 24::29 + + +   + + + + + flags + + + 30 + + + Bit 0 is a 1 if the page is AMS paged out (CMO option) else 0 + Bit 1 is a 1 if the access_rate value is valid else 0 + Bit 2 is a 1 if the affinity_log value is valid else 0 + Bit 3 is a 1 if the age value is valid else 0 + Bits 4::7 Reserved + + + + + age + + + 31 + + + Page age in units of the Page Age Granule + + + + +
+ + + + Semantics: + + - Issue icswx + If any reserved flags bits are set return H_Parameter. - - If busy response to icswx implementation dependent (may be null) - retry after backoff based upon some usage equality/priority mechanisms - else return H_Busy. + Returns H_Function if function does not exist. - - If the operation notification is asynchronous then Return - H_Success + Returns H_P2 if buffer is not 4k aligned or if the logical page number is outside of the caller’s + range. - - Wait for completion posting in CSB (CSB valid bit. 1) + count = 0; /* number of entries matching in dest */ - - The contents of the 4K naturally aligned page specified by the - csbcpb parameter are filled from the hypervisor csb and cpb with - addresses converted from real to calling partition logical real + if (Range_Search = 1) // lpn0..lpn1 range case + { + if(lpx0 is not a page owned by the calling partition) return H_P3; + if(lpx1 is less than lpx0 or outside of the LMB containing lpx0) return H_P4; + dest = buffer; + for(mem=lpx0; (mem<=lpx1) && (count < 128); mem++) + { + If (hit (mem, filter)) /* returns true if the logical page mem matches the selection criteria */ + { /* per the definition of the filter parameter above */ + fillrecord (dest, mem) ; /* fills in a record per {cross reference to table {BRF}} */ + count++ ; + Increment dest to next record (+32 bytes); + } + } + R4 = count ; R5 = mem; + If (mem > lpx1) then return H_Success else return H_CONTINUE; + } - - Return H_Success. + if (Range_Search = 0) // memory buffer case + { + dest = buffer; count = 0; + for each of lpx0..4 + Exits for each if the LPX is FFFF_FFFF_FFFF_FFFF. + if (the LPX is not a page owned by the calling partition) return H_P(3..7); + if (hit (the LPX, filter)) /* returns true if the logical page mem matches the selection criteria */ + { /* per the definition of the filter parameter above */ + fillrecord (dest, lpnx) ; /* fills in a record per {cross reference to table {BRF}} */ + count++ ; + Increment dest to next record (+32 bytes); + } + R4 = count; return H_Success; + } - - +
- -
- H_STOP_COP_OP - The architectural intent of this hcall() is to terminate a - previously initiated co-processor operation. - +
+ H_BULK_READ_HBA + H_BULK_READ_HBA returns the Reference History Bit Array entry for multiple pages in one call. The + returned values present the reference history for up to 64 HUC intervals. Starting with the high order bit + representing the most recent HUC interval, the returned value contains a one in the corresponding bit + position if the page was accessed during that interval. Due to hardware limitations, the system might not + have data for a full 64 intervals; in that case low order bits are zero filled. + - Semantics: + Syntax: + + + + + Parameters: - Check the rid parameter for validity for the caller else return - H_RH_PARM - - - If any reserved flags parameter bits are non zero then return - H_Parameter. - - - Check the csbcpb parameter for pointing within the caller’s - partition and 4K aligned else return H_P3 - - - For the shared logical resource option if the csbcpb parameter - references a rescinded shared logical resource then return - H_RESCINDED + Input: + + + flags: bits 0::63: Reserved + + + + lpx1::lpx6: The logical page number index to be used to index into appropriate position in + HBA. HBA value for a given LPX is returned in the same argument register. + + + - If the csbcpb parameter is not associated with an outstanding - coprocessor operation then return H_NOT_ACTIVE. + Output: + + + R3: Return code + + + + R4: Reserved + + + + R5: HBA corresponding to lpx1 + + + + R6: HBA corresponding to lpx2 + + + + R7: HBA corresponding to lpx3 + + + + R8: HBA corresponding to lpx4 + + + + R9: HBA corresponding to lpx5 + + + + R10: HBA corresponding to lpx6 + + + + + + + Semantics: + + - Send a kill operation to the coprocessor handling the outstanding - operation + If Reference History is not enabled, returns H_Function. - Wait for the outstanding kill operation to complete. + If a reserved flags bit is set return appropriate H_UNSUPPORTED_FLAG value. - For the CMO option, unpin any entitlement granules still pinned - for this operation and decrement the consumed partition memory - entitlement for the number of entitlement granules pinned for this - operation. + for each of lpx1..6 + Exits for each if the LPX is FFFF_FFFF_FFFF_FFFF. + If lpn1..6 not owned by the calling partition, return H_P2..7 as appropriate + Load HBA corresponding to the LPX into the high-order bits of R5-R10 + (corresponding to lpx1..6), zero out remaining lower bits of the register + and shift the register right (zero insert) by the difference between the current + time and the page’s PUT timestamp. + // end of for each lpx1..6 Return H_Success. diff --git a/Virtualization/ch_virtual_io.xml b/Virtualization/ch_virtual_io.xml index dcdacc2..2cc6cb7 100644 --- a/Virtualization/ch_virtual_io.xml +++ b/Virtualization/ch_virtual_io.xml @@ -731,6 +731,24 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo ) + + + + “ibm,drc-info” + + + + For DR + + + When present replaces the “ibm,drc-indexes”, + “ibm,drc-power-domains”, + “ibm,drc-types” and + “ibm,drc-names” properties. + This single property is a consolidation of the four pre-existing properties + and contains all of the required information. + + @@ -2082,8 +2100,13 @@ hcall ( const uint64 H_ACCEPT_LOGICAL, /* Returns in R4 handle of a shared logic Verify that the cookie parameter is valid for the calling partition, else return H_Parameter. - n If the cookie represents a logical resources that has been - rescinded by the owner, return H_RESCINDED. + + + + If the cookie represents a logical resources that has been + rescinded by the owner, return H_RESCINDED. + + @@ -2159,11 +2182,16 @@ hcall ( const uint64 H_RETURN_LOGICAL, /* Removes the logical resource from the Verify that no virtual to logical mappings exist for the referenced resource, else return H_Resource. - n This operation may require extensive processing -- in some cases - the hcall may return H_Busy to allow for improved system responsiveness - -- in these cases the state of the mapping scan is retained in the - hypervisor’s state structures such that after some number of - repeated calls the function is expected to finish. + + + + This operation may require extensive processing -- in some cases + the hcall may return H_Busy to allow for improved system responsiveness + -- in these cases the state of the mapping scan is retained in the + hypervisor’s state structures such that after some number of + repeated calls the function is expected to finish. + + @@ -2561,7 +2589,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ “ibm,trunk-adapter” property -   + + + @@ -2581,6 +2611,23 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ + + + 0x14 + + + GET_MAX_REDIRECTED_MAPPINGS + + + For platforms that support more than a single Redirected RDMA + mapping per virtual TCE. + + + + + + + @@ -2638,7 +2685,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ - n Validate the I/O address range is in the required DMA window and + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. @@ -3167,7 +3214,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Transfer into registers R4 (High order 8 bytes) and R5 (low order 8 bytes) of the UUID of the client partition that owns the virtual device ( - for the format of the UUID string. + for the format of the UUID string. @@ -3209,7 +3256,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
-
+
GET_ILLAN_SWITCHING_MODE Subfunction Semantics @@ -3233,7 +3280,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
DISABLE_INACTIVE_TRUNK_RECEPTION Subfunction - Semantics: + Semantics This subfunction is used to disable the reception of all packets for a ILLAN trunk adapter that is not the Active Trunk Adapter as set by the H_ILLAN_ATTRIBUTES hcall. @@ -3263,6 +3310,39 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
+ +
+ GET_MAX_REDIRECTED_MAPPINGS Subfunction + Semantics + + This sub-function retrieves the maximum number of additional + redirected mappings for the specified adapter. + + + + Validate parm-1, parm-2, and parm-3 are set to zero, else return + H_Parameter + + + + Validate that the given virtual IOA is an RDMA-capable server adapter, + else return H_Parameter. + + + + Store the maximum number of additional redirected mappings for + the LIOBN in R4. + + + + Store the maximum number of redirections per client IOBA in R5. + + + + Return H_Success + + +
@@ -4075,10 +4155,23 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ - If a server partition tries to get another copy of the same RTCE - table TCE it gets an error return (multiple mappings of the same physical - page are allowed, they just need to use different RTCE table TCEs just - like with physical IOA TCEs). + A server partition is guaranteed that it can create one redirected + mapping per RTCE table entry. By default if the + server partition tries to create another copy of the same RTCE table TCE + it gets an error return. Platforms that support + the H_VIOCTL hcall() might support multiple redirected + RTCE table mappings provided that they do not duplicate + existing mappings (the mappings are for different I/O operations); + if they do, the total number of such + multiple mappings per LIOBN and per RTCE page is communicated by the + “GET_MAX_REDIRECTED_MAPPINGS” sub-function of the H_VIOCTL hcall(). If the + “GET_MAX_REDIRECTED_MAPPINGS” sub-function of the + H_VIOCTL hcall() is not implemented then only + the default single copy is supported. + Multiple mappings + of the same physical page are always allowed, as + long as they originate from different RTCE table TCEs + just like with physical IOA TCEs. @@ -4107,17 +4200,17 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ The RTCE table TCE contains a valid mapping and the TCE copy - pointer references a TCE that does not contain a valid copy of the + pointers reference TCEs that do not contain a valid copy of the previous mapping in the RTCE table TCE. (The previous mapping was used for Redirected RDMA, however, the server partition has moved on and is no longer targeting the page represented by the old RTCE table TCE mapping): - Clear/invalidate the TCE copy pointer and enter the RTCE table TCE + Clear/invalidate the TCE copy pointers and enter the RTCE table TCE mapping per the input parameters to the hcall(). The RTCE table TCE contains a valid mapping and the TCE copy - pointer references a TCE that does contain a valid copy of the previous + pointers reference TCEs that do contain a valid copy of the previous mapping in the RTCE table TCE (the previous mapping is still potentially in use for Redirected RDMA, however, the partner partition has moved on and is no longer interested in the previous I/O operation). The server @@ -4194,9 +4287,11 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ /* shared logical resource. (no mappings changed) */ /* H_R_Parm: One or more r-ioba mappings are invalid -- */ /* mappings may have changed */ - /* H_Resource: An attempt was made to make multiple */ - /* redirected mappings of an RTCE table entry-- some */ - /* mappings may have changed. */ + /* H_Resource: An attempt was made to make more */ + /* redirected mappings of an RTCE table entry than the */ + /* platform supports -- some mappings may have changed. */ + /* H_IN_USE: An attempt was made to duplicate a redirected */ + /* mapping */ /* H_Hardware: The function failed due to unrecoverable */ /* hardware failure. */ hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */ @@ -4294,11 +4389,44 @@ hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */ - Prevent multiple redirected mappings of the same r-ioba: If the - r-ioba entry of the RTCE table TCE contains a valid pointer, and if that - pointer references a TCE that is a clone of the r-ioba entry of the RTCE - table TCE, then return H_Resource with the value of the loop count in - R4. + Prevent more redirected mappings of the same r-ioba than + the platform supports and/or duplicates: If the r-ioba + entry of the RTCE table TCE contains a valid pointer, and + if that pointer references a TCE that is a clone of the + r-ioba entry of the RTCE table TCE, then an additional + redirected mapping, if supported, is used else return + H_Resource with the value of the loop count in R4. + + + + Validate the liobn and ioba are not already mapped for + this entry else return H_IN_USE with the value of the + loop count in R4. + + + + Validate the number of redirected mappings for the + r-ioba does not exceed the + “ibm,max-rtce-mappings” + value for any of the adapters mapped by the RTCE else + return H_Resource with the value of the loop count in R4. + + + + Validate the number of redirected mappings for the r-ioba + does not exceed the per client IOBA value returned + from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function + else return H_Resource with the value of the loop count in R4. + + + + Validate the new entry will not cause the number of + additional redirected mappings that have already been + made for this r-liobn to exceed the maximum retrieved by the H_VIOCTL + GET_MAX_REDIRECTED_MAPPINGS sub-function else return + H_Resource with the value of the loop count in R4. + + @@ -4354,9 +4482,11 @@ hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */ /* shared logical resource (No mappings changed) /* H_R_Parm: One or more r-ioba mappings are invalid -- */ /* mappings may have changed */ - /* H_Resource: An attempt was made to make multiple */ - /* redirected mappings of an RTCE table entry-- some */ - /* mappings may have changed. */ + /* H_Resource: An attempt was made to make more */ + /* redirected mappings of an RTCE table entry than the */ + /* platform supports -- some mappings may have changed. */ + /* H_IN_USE: An attempt was made to duplicate a redirected */ + /* mapping */ /* H_Hardware: The function failed due to unrecoverable */ /* hardware failure. */ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ @@ -4477,7 +4607,7 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ - n End loop + End loop @@ -4499,11 +4629,44 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ - Prevent multiple redirected mappings of the same r-ioba: If the - r-ioba entry of the r-liobn RTCE table contains a valid pointer, and if - that pointer references a TCE entry that is a clone of the r-ioba entry - of the RTCE table, then return H_Resource with the count number in - R4. + Prevent more redirected mappings of the same r-ioba than + the platform supports and/or duplicates: If the r-ioba + entry of the RTCE table TCE contains a valid pointer, and + if that pointer references a TCE that is a clone of the + r-ioba entry of the RTCE table TCE, then an additional + redirected mapping, if supported, is used else return + H_Resource with the value of the loop count in R4. + + + + Validate the liobn and ioba are not already mapped for + this entry else return H_IN_USE with the value of the + loop count in R4. + + + + Validate the number of redirected mappings for the + r-ioba does not exceed the + “ibm,max-rtce-mappings” + value for any of the adapters mapped by the RTCE else + return H_Resource with the value of the loop count in R4. + + + + Validate the number of redirected mappings for the r-ioba + does not exceed the per client IOBA value returned + from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function + else return H_Resource with the value of the loop count in R4. + + + + Validate the new entry will not cause the number of + additional redirected mappings that have already been + made for this r-liobn to exceed the maximum retrieved by the H_VIOCTL + GET_MAX_REDIRECTED_MAPPINGS sub-function else return + H_Resource with the value of the loop count in R4. + + @@ -4670,7 +4833,7 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ - n End Loop (The critical section lasts for one iteration of the + End Loop (The critical section lasts for one iteration of the loop) @@ -5778,7 +5941,10 @@ hcall ( const int64 H_FREE_CRQ, /* Function Code */ Mark the Sub-CRQ enqueue pointer and length variables for the Sub-CRQ as invalid. - n Disable Sub-CRQ interrupts for the Sub-CRQ. + + + + Disable Sub-CRQ interrupts for the Sub-CRQ. @@ -5854,9 +6020,16 @@ hcall ( const int64 H_SEND_CRQ, /* Function Code */ msg-high: - n header: high order bit is on -- header of value 0xFF is reserved - for transport error and is invalid for input. - n format: not checked by the firmware. + + + header: high order bit is on -- header of value 0xFF is reserved + for transport error and is invalid for input. + + + + format: not checked by the firmware. + + @@ -6819,7 +6992,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ - n Validate that there is room on the specified Sub-CRQ for the + Validate that there is room on the specified Sub-CRQ for the message and allocate that message, else exit critical Section and return H_Dropped. @@ -7089,9 +7262,20 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ platform must implement all of the following subfunctions of the H_VIOCTL hcall() ( ): - n DISABLE_ALL_VIO_INTERRUPTS - n DISABLE_VIO_INTERRUPT - n ENABLE_VIO_INTERRUPT + + + + DISABLE_ALL_VIO_INTERRUPTS + + + + DISABLE_VIO_INTERRUPT + + + + ENABLE_VIO_INTERRUPT + + @@ -7251,6 +7435,10 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ the newly enqueued receive buffer descriptors have a valid bit value of 0. The hypervisor flips the value of the valid toggle bit each time it cycles from the bottom of the receive queue to the top. + Bit 5 is the Large Send Indication bit and indicates that this + packet is a large-send packet. See + + for more information on the usage of this bit. Bit 6 is the No Checksum bit and indicates that there is no checksum in this packet. See for more information on the @@ -7356,7 +7544,9 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Bit 1 = 1 if the buffer contains a valid message. Bit 1 = 0 if the buffer does not contain a valid message, in which case the device driver recycles the buffer. - Bits 2-5 Reserved. + Bits 2-4 Reserved. + Bit 5: Large Send Indication bit. If a 1, then this + indicates the packet is a large-send packet. Bit 6: No Checksum bit. If a 1, then this indicates that there is no checksum in this packet (see for more information @@ -8880,7 +9070,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ - 0-49 + 0-47 Reserved @@ -8889,6 +9079,41 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */   + + + 48 + + + Large Send Indication Supported + + + The bit is implemented when the large send indication bit in + the I/O descriptor passed to H_SEND_LOGICAL_LAN is + supported by firmware. + 0: Software must not request large send indication, + by setting Bit 5 of the buffer descriptor. + 1: Software may request large send indication, by + setting Bit 5 of the buffer descriptor. + + + + + 49 + + + Port Disabled + + + When the bit is a 1, the port is disabled. When + the port is disabled, no Ethernet traffic will be + permitted to be transmitted or received. + H_Parameter will be returned if this bit is turned + on in either the reset or set masks. On firmware + that does not support this function, bit 49 is + reserved and required to be 0. OS can infer that + means the port is enabled. + + 50 @@ -10394,6 +10619,66 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
+ +
+ ILLAN Large Send Indication option + + This option allows the virtual device to send an + indication to the receiver that the data being sent by + H_SEND_LOGICAL_LAN contains a large send packet. + +
+ General + + The following are the general requirements for this option. For H_SEND_LOGICAL_LAN changes, see + . + + + + R1--1. + + + For the ILLAN Large send indication option: + The platform must do all the following: + + + + Implement the H_ILLAN_ATTRIBUTES hcall(). + + + + Implement the Large Send Indication bit of the ILLAN Attributes as defined in + . + + + + + + +
+ +
+ H_SEND_LOGICAL_LAN Semantic Changes + + The following are the required semantic changes to the H_SEND_LOGICAL_LAN hcall(). + + + + R1--1. + + + For the ILLAN Large send indication option: + When the Large Send Indication bit of the first buffer descriptor is set to 1, + then the firmware for the H_SEND_LOGICAL_LAN hcall() must set the Large Send Indication + bit in the receiver's receive queue entry to 1 when the packet is copied to the + destination receive buffer. + + + +
+
@@ -11755,31 +12040,68 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Parameters: - n termno: The unit address of the Vterm IOA, from the - “reg” property of the Vterm IOA. + + + + termno: The unit address of the Vterm IOA, from the + “reg” property of the Vterm IOA. + + Semantics: - n Hypervisor checks the termno parameter for validity against the - Vterm IOA unit addresses assigned to the partition, else return - H_Parameter. - n Hypervisor returns H_Hardware if it detects that the virtual - console terminal physical connection is not working. - n Hypervisor returns H_Closed if it detects that the virtual - console associated with the termno parameter is not open (in the case of - connection to a server Vterm IOA, this means that the server code has not - made the connection to this specific client Vterm IOA). - n Hypervisor returns H_Success in all other cases, returning - maximum number of characters available in the partition’s virtual - console terminal input buffer (up to 16) -- a len value of 0 indicates - that the input buffer is empty. - n Upon return with H_Success register R4 contains the number of - bytes (if any) returned in registers R5 and R6. - n Upon return with H_Success the return character string starts in - the high order byte of register R5 and proceeds toward the low order byte - in register R6 for the number of characters specified in R4. The contents - of all other byte locations of registers R5 and R6 are undefined. + + + + Hypervisor checks the termno parameter for validity against the + Vterm IOA unit addresses assigned to the partition, else return + H_Parameter. + + + + Hypervisor returns H_Hardware if it detects that the virtual + console terminal physical connection is not working. + + + + Hypervisor returns H_Closed if it detects that the virtual + console associated with the termno parameter is not open (in the case of + connection to a server Vterm IOA, this means that the server code has not + made the connection to this specific client Vterm IOA). + + + + Hypervisor returns H_Success in all other cases, returning + maximum number of characters available in the partition’s virtual + console terminal input buffer (up to 16) -- a len value of 0 indicates + that the input buffer is empty. + + + + Upon return with H_Success register R4 contains the number of + bytes (if any) returned in registers R5 and R6. + + + + Upon return with H_Success the return character string starts in + the high order byte of register R5 and proceeds toward the low order byte + in register R6 for the number of characters specified in R4. The contents + of all other byte locations of registers R5 and R6 are undefined. + + + + Upon return with H_Success register R4 contains the number of + bytes (if any) returned in registers R5 and R6. + + + + Upon return with H_Success the return character string starts in + the high order byte of register R5 and proceeds toward the low order byte + in register R6 for the number of characters specified in R4. The contents + of all other byte locations of registers R5 and R6 are undefined. + +
@@ -11797,35 +12119,67 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Parameters: - n termno: The unit address of the Vterm IOA, from the - “reg” property of the Vterm IOA. - n len: The length of the string to transmit through the virtual - terminal port. Valid values are in the range of 0-16. - n char0_7 and char8_15: The string starts in the high order byte of - register R6 and proceeds toward the low order byte in register R7 + + + + termno: The unit address of the Vterm IOA, from the + “reg” property of the Vterm IOA. + + + + len: The length of the string to transmit through the virtual + terminal port. Valid values are in the range of 0-16. + + + + char0_7 and char8_15: The string starts in the high order byte of + register R6 and proceeds toward the low order byte in register R7 + + + Semantics: - n Hypervisor checks the termno parameter for validity against the - Vterm IOA unit addresses assigned to the partition, else return - H_Parameter. - n Hypervisor returns H_Hardware if it detects that the virtual - console terminal physical connection is not working. - n Hypervisor returns H_Closed if it detects that the virtual - console session is not open (in the case of connection to a server Vterm - IOA, this means that the server code has not made the connection to this - specific client Vterm IOA). - n If the length parameter is outside of the values 0-16 the - hypervisor immediately returns H_Parameter with no other action. - n If the partition’s virtual console terminal buffer has room - for the entire string, the hypervisor queues the output string and - returns H_Success. - Note: There is always room for a zero length string (a - zero length write can be used to test the virtual console terminal - connection). - n If the buffer cannot hold the entire string, no data is enqueued - and the return code is H_Busy. + + + + Hypervisor checks the termno parameter for validity against the + Vterm IOA unit addresses assigned to the partition, else return + H_Parameter. + + + + Hypervisor returns H_Hardware if it detects that the virtual + console terminal physical connection is not working. + + + + Hypervisor returns H_Closed if it detects that the virtual + console session is not open (in the case of connection to a server Vterm + IOA, this means that the server code has not made the connection to this + specific client Vterm IOA). + + + + If the length parameter is outside of the values 0-16 the + hypervisor immediately returns H_Parameter with no other action. + + + + If the partition’s virtual console terminal buffer has room + for the entire string, the hypervisor queues the output string and + returns H_Success. + Note: There is always room for a zero length string (a + zero length write can be used to test the virtual console terminal + connection). + + + + If the buffer cannot hold the entire string, no data is enqueued + and the return code is H_Busy. + + @@ -12610,11 +12964,17 @@ hcall ( const uint64 H_REGISTER_VTERM, /* Makes connection between server and */ If partner-partition-id and partner-unit-addr together do not match a valid partition ID and unit address pair in the list of valid connections for this unit-address, then return H_Parameter, - n Else make connection between the server Vterm IOA specified by - unit-address and the client Vterm IOA specified by the - partner-partition-id and partner-unit-addr pair, allowing future - H_PUT_TERM_CHAR and H_GET_TERM_CHAR operations to flow between the two - Vterm IOAs, and return H_Success. + + + + Else make connection between the server Vterm IOA specified by + unit-address and the client Vterm IOA specified by the + partner-partition-id and partner-unit-addr pair, allowing future + H_PUT_TERM_CHAR and H_GET_TERM_CHAR operations to flow between the two + Vterm IOAs, and return H_Success. + + + @@ -13982,13 +14342,7 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne physical port. The implementation support is provided by code running in a server partition that uses the mechanisms of the Synchronous VIO Infrastructure (or equivalent thereof as seen by the client) to service I/O - requests for code running in a client partition - The server partition for VNIC is expected to be part of the - platform firmware and therefore an OS interface is not provided in this - architecture for the server side. However, the platform firmware is still - expected to be implemented by a partition, and hence the term - “server partition.” - . The client partition appears to enjoy the services of its own + requests for code running in a client partition. The client partition appears to enjoy the services of its own NIC adapter. The terms server and client partitions refer to platform partitions that are respectively servers and clients of requests, usually I/O operations, using the physical NIC that is assigned to the server @@ -14175,10 +14529,11 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Properties of the <emphasis role="bold"><literal>vnic</literal></emphasis> Node in the OF Device Tree - + - + + @@ -14188,7 +14543,12 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - Required? + Required for vnic? + + + + + Required for vnic-server? @@ -14198,7 +14558,7 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - + @@ -14206,13 +14566,15 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - Y + YValue = “ibm,vnic” + + + YValue = “ibm,vnic-server” Standard property name per , specifying the - virtual device name, the value shall be - “vnic”. + virtual device name. @@ -14224,6 +14586,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + N + Standard property name per , specifying the @@ -14240,6 +14605,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne NA + + NA + Property not present. @@ -14251,14 +14619,15 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - Y + YValue includes: “ibm,vnic” + + + YValue includes: “ibm,vnic-server” Standard property name per , specifying the - programming models that are compatible with this virtual IOA, - the value shall include - “IBM,vnic”. + programming models that are compatible with this virtual IOA. @@ -14268,11 +14637,14 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - See definition column + Present if appropriate. Present if appropriate. + +   + @@ -14283,6 +14655,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + Y + Property name specifying the unique and persistent location code associated with this virtual IOA. @@ -14297,6 +14672,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + Y + Standard property name per , specifying the unit @@ -14318,15 +14696,28 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - Y + YValue = a single triplet + + + YValue = two triplet Property name specifying the DMA window associated with - this virtual IOA presented as an encoded array of three values + this virtual IOA presented as an encoded array of one or more sets of three values (triplet) (LIOBN, phys, size) encoded as with encode-int, encode-phys, and encode-int. + For the vnic-server the two tripples describe two window panes: + the first describes the window pane used to map server partition memory; + the second is the window pane through which the client partition maps + its memory that it makes available to the server partition. + (Note: the mapping between + the LIOBN in the second window pane of a server virtual IOA’s + “ibm,my-dma-window” + property and the corresponding client IOA’s RTCE table is made when the + CRQ successfully completes registration. See + .) @@ -14338,6 +14729,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + Y + Standard property name specifying the interrupt source number and sense code associated with this virtual IOA @@ -14358,6 +14752,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne For DR + + For DR + Present if the platform implements DR for this node. @@ -14372,6 +14769,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne See definition column + + See definition column + Property name, to define the package’s dma address size format. The property value specifies the number of cells @@ -14393,6 +14793,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne See definition column + + See definition column + Property name, to define the package’s dma address format. The property value specifies the number of cells that @@ -14413,6 +14816,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + NA + Standard property name per , specifying the @@ -14429,6 +14835,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + NA + Standard property name per , specifying the @@ -14445,6 +14854,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + NA + Standard property name as per . @@ -14461,6 +14873,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + NA + Standard property name as per . @@ -14477,6 +14892,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + NA + Standard property name per , to indicate maximum @@ -14492,6 +14910,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y + + NA + Standard property name per , to indicate network @@ -14500,7 +14921,10 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - “interrupt-ranges” + “interrupt-ranges” + + + Y Y @@ -14512,6 +14936,52 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne ranges. + + + “ibm,vf-loc-code” + + + NA + + + Y + + + Vendor unique property name to define the physical device + virtual function upon which the vnic-server runs. The value is + that of the “ibm,loc-code” + property of the physical device virtual function. + + + + + “ibm,vnic-mode” + + + NA + + + Y + + + Vendor unique property that represents the operational + mode in which the vnic-server runs. + + + + + “ibm,vnic-client-mac” + + + NA + + + Y + + + Vendor unique property that represents a vNIC server's client MAC address. + +