| Bound program access |
|---|
|
Built-in number for MATMIF is 670. MATMIF ( receiver : address materialization_option : unsigned binary(2) ) : signed binary(4) /* result */ |
The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release. The data returned by this instruction is subject to change each and every release. Fields may be added, deleted, reordered, and/or have their unit of measure changed. There will be no attempt made to maintain any compatibility from release to release.
Information specified by the materialization option operand is materialized into the template addressed by the receiver operand. Upon successful completion, result is set to binary 0.
In the case where the requested data cannot be returned, the EUNKNOWN error number is returned in the result.
The receiver specifies a space that is to receive the materialized information. The space pointer specified must address a 16-byte aligned area. If not, the EFAULT error number is returned in the result.
The materialization option specifies which information is to be materialized. If an invalid value is specified, the EINVAL error number is returned in the result.
A summary of the allowable hex values
for materialization option follows.
Table 1. Materialize Machine Information options
| Materialization Option | Page |
|---|---|
| Hex 0001 - Option 0001 information (for current partition) | reference #1 |
| Hex 0002 - Option 0002 information (for current partition) | reference #2 |
The receiver template has the following format
| Offset | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex |
| Field Name |
| Data Type and Length | ||||||||
| 0 | 0 |
| Materialization size specification |
| Char(8) | ||||||||
| 0 | 0 |
| Number of bytes provided |
| UBin(4) | ||||||||
| 4 | 4 |
| Number of bytes available |
| UBin(4) | ||||||||
| 8 | 8 |
| Information |
| Char(*) | ||||||||
| * | * |
| --- End --- |
|
| ||||||||
The first 4 bytes identify the total number of bytes provided for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the ENOSPC error number to be returned in the result.
The second 4 bytes identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged. No error numbers (other than the ENOSPC described previously) are returned if the receiver contains insufficient area for the materialization.
The following information requires receivers of varying lengths. The information that will be materialized and their materialization option values follow. If the system does not support a function, hex zeros will be returned in that field. (Ref #1.)
| Offset | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex | Field Name | Data Type and Length | ||||||||||||||
| 8 | 8 | Maximum memory | UBin(8) | ||||||||||||||
| 16 | 10 | Minimum memory | UBin(8) | ||||||||||||||
| 24 | 18 | Dispatch wheel rotation period | UBin(8) | ||||||||||||||
| 32 | 20 | Partition ID | UBin(4) | ||||||||||||||
| 36 | 24 | Indicators | Char(4) | ||||||||||||||
| 36 | 24 | Reserved (binary 0) | Bits 0-28 | ||||||||||||||
| 36 | 24 | Scaled processor time indicator | Bit 29 | ||||||||||||||
|
|||||||||||||||||
| 36 | 24 | Bound hardware threads indicator | Bit 30 | ||||||||||||||
|
|||||||||||||||||
| 36 | 24 | Dedicated processors indicator | Bit 31 | ||||||||||||||
|
|||||||||||||||||
| 40 | 28 | Maximum processors in the physical machine | UBin(4) | ||||||||||||||
| 44 | 2C | Minimum virtual processors | UBin(4) | ||||||||||||||
| 48 | 30 | Maximum virtual processors | UBin(4) | ||||||||||||||
| 52 | 34 | Minimum processing capacity | UBin(4) | ||||||||||||||
| 56 | 38 | Maximum processing capacity | UBin(4) | ||||||||||||||
| 60 | 3C | Processing capacity delta | UBin(4) | ||||||||||||||
| 64 | 40 | Minimum interactive capacity percentage | UBin(4) | ||||||||||||||
| 68 | 44 | Maximum interactive capacity percentage | UBin(4) | ||||||||||||||
| 72 | 48 | Hardware threads per processor | UBin(2) | ||||||||||||||
| 74 | 4A | Partition name | Char(256) | ||||||||||||||
| 330 | 14A | Reserved (binary 0) | Char(6) | ||||||||||||||
| 336 | 150 | Memory delta | UBin(8) | ||||||||||||||
| 344 | 158 | Configured virtual processors | UBin(4) | ||||||||||||||
| 348 | 15C | Configured processing capacity | UBin(4) | ||||||||||||||
| 352 | 160 | Configured interactive capacity percentage | UBin(4) | ||||||||||||||
| 356 | 164 | Configured variable processing capacity weight | UBin(4) | ||||||||||||||
| 360 | 168 | Configured memory | UBin(8) | ||||||||||||||
| 368 | 170 | --- End --- | |||||||||||||||
Minimum memory is the minimum amount of memory (in units of megabytes) that is needed in this partition.
Maximum memory is the maximum amount of memory (in units of megabytes) that can be assigned to this partition.
Dispatch wheel rotation period is the number of nanoseconds in the hypervisor's scheduling window. Each virtual processor will be given the opportunity to execute on a physical processor sometime during this period. The amount of time each virtual processor is able to use in the hypervisor's scheduling window on a physical processor corresponds to the partition's processing capacity. The value of processing capacity is returned in option hex 0002 of this instruction.
Partition ID is the identifier of this partition. It is unique within a physical machine.
Bound hardware threads indicator indicates whether or not hardware threads are bound. Hardware threads are not bound indicates that the system can not assume that a set of hardware threads will always be dispatched together on a physical processor. Hardware threads are bound indicates that a set of hardware threads will always be dispatched together on a physical processor. This allows an operating system to make scheduling decisions based on cache affinity and work load.
Dedicated processors indicator indicates whether or not the partition uses only dedicated physical processors. Partition has dedicated processors indicates that this partition uses only dedicated physical processors. This means that each virtual processor in the partition has a corresponding entire physical processor. Partition shares processors indicates that this partition uses physical processors from a shared pool of physical processors. The number of virtual processors represents the maximum number of concurrent units of execution that can be active in the partition at any point in time. Each virtual processor has the processing capacity of some fraction of a physical processor. One or more partitions may be executing on the physical processors in the shared processor pool at any given point in time.
The scaled processor time indicator indicates whether processor time may or may not be scaled during the current IPL. If the scaled processor time indicator is 0, then materialized values of scaled and unscaled processor times are equivalent during the current IPL. If the scaled processor time indicator is 1, then materialized values of scaled and unscaled processor times are not equivalent during the current IPL.
Over any interval, the average relative processor speed (i.e. processor speed relative to nominal) is indicated by the ratio of scaled processor time to unscaled processor time elapsed during the interval. When the scaled processor time indicator is 0, scaled and unscaled processor times are equivalent, and their ratio over any interval is 1:1, indicating that the processor's relative speed is 1X nominal. When the scaled processor time indicator is 1, scaled and unscaled processor times are not equivalent, and the ratio of their elapsed values over any interval indicates the processor's average relative speed over the interval.
For example, consider MATRMD hex 26 data is available at the start and end of an interval. The ratio of the elapsed scaled processor utilized time to elapsed processor utilized time indicates the average relative processor speed while the processor was being utilized during the interval. The same analysis is applicable to all categories of processor time accumulated during an interval (i.e. processor interrupted time, processor stolen time, processor donated time, processor idle time, and process/thread time) -- the ratio of the scaled to unscaled time indicates the relative processor speed for the accumulated time category. Note that when the scaled processor time indicator is 0, the ratio of scaled to unscaled processor times is always 1:1.
Maximum processors in the physical machine is the maximum number of physical processors that can be active in this physical machine without physically installing additional processors. This field includes currently active processors and any standby processors that are present in the physical machine.
Minimum virtual processors is the minimum number of virtual processors that are needed in this partition.
Maximum virtual processors is the maximum number of virtual processors that can be assigned to this partition.
Minimum processing capacity is the minimum amount of processing capacity (in units of 1/100 of a physical processor) that is needed in this partition.
Maximum processing capacity is the maximum amount of processing capacity (in units of 1/100 of a physical processor) that can be assigned to this partition.
Processing capacity delta is the delta (in units of 1/100 of a physical processor) that can be added to or removed from this partition's processing capacity.
Minimum interactive capacity percentage is the minimum value that can be set for this partition's interactive capacity percentage.
Maximum interactive capacity percentage is the maximum value that can be set for this partition's interactive capacity percentage.
Hardware threads per processor is the number of hardware threads per processor when hardware multi-threading is enabled.
Partition name is the name that has been assigned to this partition. This field is a null-terminated ASCII character string.
Memory delta is the delta (in units of megabytes) that can be added to or removed from this partition's memory.
Configured virtual processors is the number of virtual processors that are configured for this partition. It does not include the standby (on demand) processors.
Configured processing capacity is the processing capacity (in units of 1/100 of a physical processor) that is configured for this partition.
Configured variable processing capacity weight is the variable processing capacity weight that is configured for this partition.
Configured memory is the physical memory size (in units of megabytes) that is configured for this partition. It does not include the standby (on demand) memory.
| Offset | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Dec | Hex | Field Name | Data Type and Length | ||||||||||||||
| 8 | 8 | Usable memory | UBin(8) | ||||||||||||||
| 16 | 10 | CPU time since IPL | UBin(8) | ||||||||||||||
| 24 | 18 | Interactive time since IPL | UBin(8) | ||||||||||||||
| 32 | 20 | Excess interactive time since IPL | UBin(8) | ||||||||||||||
| 40 | 28 | Shared processor pool idle time since IPL | UBin(8) | ||||||||||||||
| 48 | 30 | Indicators | Char(4) | ||||||||||||||
| 48 | 30 | Reserved (binary 0) | Bits 0-26 | ||||||||||||||
| 48 | 30 | Scaled processor time indicator | Bit 27 | ||||||||||||||
|
|||||||||||||||||
| 48 | 30 | Service aggregation point indicator | Bit 28 | ||||||||||||||
|
|||||||||||||||||
| 48 | 30 | Capped partition indicator | Bit 29 | ||||||||||||||
|
|||||||||||||||||
| 48 | 30 | Hardware multi-threading indicator | Bit 30 | ||||||||||||||
|
|||||||||||||||||
| 48 | 30 | Shared processor pool idle time since IPL indicator | Bit 31 | ||||||||||||||
|
|||||||||||||||||
| 52 | 34 | Processors in the physical machine | UBin(4) | ||||||||||||||
| 56 | 38 | Usable virtual processors | UBin(4) | ||||||||||||||
| 60 | 3C | Physical processors in the shared processor pool | UBin(4) | ||||||||||||||
| 64 | 40 | Unallocated processor capacity in the partition group | UBin(4) | ||||||||||||||
| 68 | 44 | Usable processing capacity | UBin(4) | ||||||||||||||
| 72 | 48 | Usable variable processing capacity weight | UBin(4) | ||||||||||||||
| 76 | 4C | Unallocated variable processing capacity weight | UBin(4) | ||||||||||||||
| 80 | 50 | Minimum required processing capacity | UBin(4) | ||||||||||||||
| 84 | 54 | Interactive capacity percentage | UBin(4) | ||||||||||||||
| 88 | 58 | Partition group ID | UBin(2) | ||||||||||||||
| 90 | 5A | Shared processor pool ID | UBin(2) | ||||||||||||||
| 92 | 5C | Interactive threshold | UBin(2) | ||||||||||||||
| 94 | 5E | Reserved (binary 0) | Char(2) | ||||||||||||||
| 96 | 60 | Unallocated interactive processor capacity in the partition group | Bin(4) | ||||||||||||||
| 100 | 64 | Scaled CPU time since IPL | UBin(8) | ||||||||||||||
| 108 | 6C | Reserved (binary 0) | Char(4) | ||||||||||||||
| 112 | 70 | --- End --- | |||||||||||||||
Usable memory is the amount of usable memory (in units of megabytes) currently allocated to this partition.
CPU time since IPL is the number of nanoseconds of processor time used since IPL.
Interactive time since IPL is the number of nanoseconds of processor time used by interactive processes since IPL. An interactive process is any process doing 5250 display device I/O. For additional information on interactive processes, see the System i™ Performance Capabilities Reference manual, SC41-0607, which is available in the i5/OS® Information Center.
Excess interactive time since IPL is the number of nanoseconds of processor time used by interactive processes since IPL, that exceeded interactive capacity.
Shared processor pool idle time since IPL is the number of nanoseconds of processor time that the shared processor pool has been idle since IPL, when shared processor pool idle time since IPL was materialized.
Service aggregation point indicator indicates whether or not this partition has a service aggregation point. A service aggregation point is used by the operating system to report problems to HMC.
Capped partition indicator indicates whether or not the partition is allowed to use more than its processing capacity. An uncapped partition is allowed to use more than its processing capacity if processing capacity is available in the shared processor pool. A capped partition is not allowed to use more than its processing capacity even if the partition has work to do and there is processing capacity available in the shared processor pool.
Hardware multi-threading indicator indicates whether or not hardware multi-threading is enabled. Hardware multi-threading is enabled indicates that hardware multi-threading is active. Hardware multi-threading is not enabled indicates that hardware multi-threading is inactive. Hardware multi-threading refers to the ability of a processor to be multi-threaded. When a processor is multi-threaded, multiple tasks of execution can be loaded into the same processor. Each task of execution is referred to as a hardware thread. When hardware multi-threading is enabled, hardware threads per processor indicates the number of hardware threads each processor has.
The scaled processor time indicator indicates whether processor time may or may not be scaled during the current IPL. If the scaled processor time indicator is 0, then materialized values of scaled and unscaled processor times are equivalent during the current IPL. If the scaled processor time indicator is 1, then materialized values of scaled and unscaled processor times are not equivalent during the current IPL.
Over any interval, the average relative processor speed (i.e. processor speed relative to nominal) is indicated by the ratio of scaled processor time to unscaled processor time elapsed during the interval. When the scaled processor time indicator is 0, scaled and unscaled processor times are equivalent, and their ratio over any interval is 1:1, indicating that the processor's relative speed is 1X nominal. When the scaled processor time indicator is 1, scaled and unscaled processor times are not equivalent, and the ratio of their elapsed values over any interval indicates the processor's average relative speed over the interval.
For example, consider MATRMD hex 26 data is available at the start and end of an interval. The ratio of the elapsed scaled processor utilized time to elapsed processor utilized time indicates the average relative processor speed while the processor was being utilized during the interval. The same analysis is applicable to all categories of processor time accumulated during an interval (i.e. processor interrupted time, processor stolen time, processor donated time, processor idle time, and process/thread time) -- the ratio of the scaled to unscaled time indicates the relative processor speed for the accumulated time category. Note that when the scaled processor time indicator is 0, the ratio of scaled to unscaled processor times is always 1:1.
Shared processor pool idle time since IPL indicator indicates whether or not the shared processor pool idle time since IPL was successfully materialized. Shared processor pool idle time since IPL was materialized indicates that the shared processor pool idle time since IPL was successfully materialized and contains valid information. Shared processor pool idle time since IPL was not materialized indicates that the shared processor pool idle time since IPL was not materialized (the partition is not authorized to retrieve this information) and should not be used.
Processors in the physical machine is the number of physical processors in this physical machine that are available for customer use. This does not include temporary processors on demand that have not been turned on.
Usable virtual processors is the number of usable virtual processors in this partition.
Physical processors in the shared processor pool is the number of physical processors that are allocated to the shared processor pool in which this partition is executing.
Unallocated processing capacity in the partition group is the amount of processing capacity (in units of 1/100 of a physical processor) in this partition's group that is available to be allocated to processing capacity.
Usable processing capacity is the amount of processing capacity (in units of 1/100 of a physical processor) currently available to the partition. For a partition using dedicated processors this value represents the number of virtual processors currently active in the partition. For a partition using shared processors this value represents this partition's share of processors from its shared processor pool.
Usable variable processing capacity weight is the weighting factor that is used to assign additional unused CPU cycles (from the shared processor pool) to the partition. Variable processing capacity weight is used for uncapped partitions when they compete for unused CPU cycles in the shared pool. This factor is ranged from 0 - 255. The larger the weight, the more the chance this partition will get additional CPU cycles from the pool. A value of 0 effectively caps this partition at its processing capacity.
Unallocated variable processing capacity weight is the amount of capacity weight that is available for allocation to the variable processing capacity weight.
Minimum required processing capacity is the amount of processing capacity (in units of 1/100 of a physical processor) that the operating system requires in this partition.
Interactive capacity percentage is this partition's portion (in hundredths of a percent) of the physical machine's interactive capacity. For example, if the physical machine was allowed to do 2000 units of interactive work per second, and this field was 5000 (50%), then this partition would be allowed to perform 1000 units of interactive work per second.
Partition group ID identifies the LPAR group that this partition is a member of. A LPAR group (aka partition group) is a set of partitions on a physical machine that a Work Load Manager (WLM) will manage to achieve its goals. WLM manages the partitions by moving resources from one partition in the group to another partition in the group.
Shared processor pool ID identifies the shared processor pool this partition is a member of. This field should only be used when partition shares processors. A shared processor pool is a set of physical processors on the physical machine that is used to run a set of shared processor partitions that exist on this physical machine.
Interactive threshold is the maximum interactive processor utilization (in hundredths of a percent) which can be sustained in this partition, without causing a disproportionate increase in system overhead. For example, a value of 2379 means that the threshold is 23.79%. On a machine with no limit on interactive utilization, the value returned will be 10000 (100%).
Unallocated interactive capacity percentage in the partition group is the portion (in hundredths of percent) of the physical machine's interactive capacity that is available to be allocated to interactive capacity percentage of partitions in this partition's group. 0 will be returned if this instruction is issued on a system with firmware level hex 00 -1 will be returned if this instruction is issued on a system with firmware level hex 10 and the release level of that firmware does not support this function.
Scaled CPU time since IPL is the number of nonoseconds of scaled processor utilized time used since IPL.
If scaled processor time indicator is 0, the scaled CPU time since IPL will equal the CPU time since IPL. If scaled processor time indicator is 1, the partition's processors may operate at different speeds during the current IPL, and the scaled CPU time since IPL and CPU time since IPL unscaled may differ. The ratio between scaled and unscaled utilized times over any interval is indicative of the processor's speed, relative to nominal, while being used productively during the interval.
The result will be set to one of the following:
|
EFAULT |
3408 - The address used for an argument was not correct. |
|
EINVAL |
3021 - The value specified for the argument is not correct. |
|
ENOSPC |
3404 - No space available. |
|
EUNKNOWN |
3474 - Unknown system state. |
06 Addressing
08 Argument/Parameter
10 Damage Encountered
1A Lock State
1C Machine-Dependent
20 Machine Support
22 Object Access
24 Pointer Specification
2E Resource Control Limit
32 Scalar Specification
36 Space Management
44 Protection Violation