qclib
Macros | Enumerations | Functions
query_capacity.h File Reference

Go to the source code of this file.

Macros

#define QC_VERSION   "2.3.1"
 
#define CONFIG_DEBUG_TIMESTAMPS
 

Enumerations

enum  qc_layer_types {
  QC_LAYER_TYPE_CEC = 1 , QC_LAYER_TYPE_LPAR_GROUP = 8 , QC_LAYER_TYPE_LPAR = 2 , QC_LAYER_TYPE_ZVM_HYPERVISOR = 3 ,
  QC_LAYER_TYPE_ZVM_CPU_POOL = 4 , QC_LAYER_TYPE_ZVM_RESOURCE_POOL = 4 , QC_LAYER_TYPE_ZVM_GUEST = 5 , QC_LAYER_TYPE_KVM_HYPERVISOR = 6 ,
  QC_LAYER_TYPE_KVM_GUEST = 7 , QC_LAYER_TYPE_ZOS_HYPERVISOR = 9 , QC_LAYER_TYPE_ZOS_TENANT_RESOURCE_GROUP = 10 , QC_LAYER_TYPE_ZOS_ZCX_SERVER = 11
}
 
enum  qc_layer_categories { QC_LAYER_CAT_GUEST = 1 , QC_LAYER_CAT_HOST = 2 , QC_LAYER_CAT_POOL = 3 }
 
enum  qc_part_chars { QC_PART_CHAR_DEDICATED = 1 , QC_PART_CHAR_SHARED = 2 , QC_PART_CHAR_LIMITED = 4 }
 
enum  qc_cappings { QC_CAPPING_OFF = 0 , QC_CAPPING_SOFT = 1 , QC_CAPPING_HARD = 2 }
 
enum  qc_model_families { QC_TYPE_FAMILY_IBMZ = 0 , QC_TYPE_FAMILY_LINUXONE = 1 }
 
enum  qc_attr_id {
  qc_adjustment = 0 , qc_capability = 1 , qc_capacity_adjustment_indication = 2 , qc_capacity_change_reason = 3 ,
  qc_capping = 4 , qc_capping_num = 5 , qc_cluster_name = 6 , qc_control_program_id = 7 ,
  qc_cp_absolute_capping = 8 , qc_cp_capacity_cap = 9 , qc_cp_capped_capacity = 10 , qc_cp_dispatch_limithard = 11 ,
  qc_cp_dispatch_type = 12 , qc_cp_limithard_cap = 13 , qc_cp_weight_capping = 14 , qc_limithard_consumption = 15 ,
  qc_has_multiple_cpu_types = 16 , qc_ifl_absolute_capping = 17 , qc_ifl_capacity_cap = 18 , qc_ifl_capped_capacity = 19 ,
  qc_ifl_dispatch_limithard = 20 , qc_ifl_dispatch_type = 21 , qc_ifl_limithard_cap = 22 , qc_ifl_weight_capping = 23 ,
  qc_ziip_absolute_capping = 66 , qc_ziip_capacity_cap = 67 , qc_ziip_capped_capacity = 68 , qc_ziip_dispatch_limithard = 69 ,
  qc_ziip_dispatch_type = 70 , qc_ziip_limithard_cap = 71 , qc_ziip_weight_capping = 72 , qc_layer_category = 24 ,
  qc_layer_category_num = 25 , qc_layer_extended_name = 26 , qc_layer_name = 27 , qc_layer_type = 28 ,
  qc_layer_type_num = 29 , qc_layer_uuid = 30 , qc_manufacturer = 31 , qc_mobility_enabled = 32 ,
  qc_has_secure = 77 , qc_secure = 78 , qc_model = 33 , qc_model_capacity = 34 ,
  qc_type_family = 65 , qc_num_cp_dedicated = 35 , qc_num_cp_shared = 36 , qc_num_cp_total = 37 ,
  qc_num_cpu_configured = 38 , qc_num_cpu_dedicated = 39 , qc_num_cpu_reserved = 40 , qc_num_cpu_shared = 41 ,
  qc_num_cpu_standby = 42 , qc_num_cpu_total = 43 , qc_num_ifl_dedicated = 44 , qc_num_ifl_shared = 45 ,
  qc_num_ifl_total = 46 , qc_num_ziip_dedicated = 73 , qc_num_ziip_shared = 74 , qc_num_ziip_total = 75 ,
  qc_partition_char = 47 , qc_partition_char_num = 48 , qc_partition_number = 49 , qc_plant = 50 ,
  qc_secondary_capability = 51 , qc_sequence_code = 52 , qc_type = 53 , qc_prorated_core_time = 54 ,
  qc_num_cp_threads = 55 , qc_num_ifl_threads = 56 , qc_num_ziip_threads = 76 , qc_num_core_total = 57 ,
  qc_num_core_configured = 58 , qc_num_core_standby = 59 , qc_num_core_reserved = 60 , qc_num_core_dedicated = 61 ,
  qc_num_core_shared = 62 , qc_type_name = 63 , qc_lic_identifier = 64
}
 

Functions

void * qc_open (int *rc)
 
void qc_close (void *hdl)
 
int qc_get_num_layers (void *hdl, int *rc)
 
int qc_get_attribute_string (void *hdl, enum qc_attr_id id, int layer, const char **value)
 
int qc_get_attribute_int (void *hdl, enum qc_attr_id id, int layer, int *value)
 
int qc_get_attribute_float (void *hdl, enum qc_attr_id id, int layer, float *value)
 
void qc_export_json (void *hdl)
 

Enumeration Type Documentation

◆ qc_attr_id

enum qc_attr_id

Defines the attributes retrievable by the API. Attributes can exist for multiple layers. Also, attributes will only be valid if retrieved as the correct type.

The following tables detail which attributes of what types are available for what layers. The letter encoding in the 'Src' column describes how the value is gained:

  • S: Provided by /proc/sysinfo, which is present in all Linux on z flavors.
  • F: Provided by firmware as made available through the sysfs filesystem.
  • H: Provided by hypfs, which is (preferably) available through debugfs at /sys/kernel/debug/s390_hypfs, or s390_hypfs (typically mounted at /sys/hypervisor/s390). Proper file access privileges required.
  • h: See H, but provided by debugfs exclusively.
  • V: Provided by the STHYI instruction.
    • z/VM Linux guests: Requires z/VM 6.3 with APAR VM65419 or higher. UM34746 for z/VM 6.3.0 APAR VM65716 is required for LPAR groups support (see layer QC_LAYER_TYPE_LPAR_GROUP).
    • KVM Linux guests: Requires Linux kernel 4.8 or higher in the KVM host.
    • Linux LPAR: Requires Linux kernel 4.15 or higher in the KVM host.
    • zCX: Requires z/OS 2.4 or higher.

Several letters indicate the order in which the value is attempted to be acquired. If the extraction of the value in a later phase succeeds, it will overwrite the value acquired in an earlier phase. If the extraction of the value in a later phase does not succeed, it will not dismiss the existing value, if a previous phase has set it before.

SMT

SMT was introduced starting with z13/LinuxONE.
When SMT is turned off (or not available), the terms core and CPU are synonymous. But when SMT is enabled, CPU refers to a thread running on a core.
As a general rule, CP, IFL and zIIP counts (eg. qc_num_cp_total, qc_num_ifl_total and qc_num_ziip_total respectively)

Notes

Attributes for CECs (layer 0) Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_CEC
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_HOST
qc_layer_type string Hardcoded to "CEC"
qc_layer_category string Hardcoded to "HOST"
qc_layer_name string F V CPC name of machine. Available in Linux kernel 3.0 or higher.
qc_manufacturer string S V
qc_type string S V
qc_type_name string S  
qc_type_family int S  
qc_model_capacity string S  
qc_model string S  
qc_sequence_code string S V
qc_lic_identifier string S   Note: Requires Linux kernel 4.16 or higher, and IBM z14 or later
qc_plant string S V
qc_num_core_total int S Sum of qc_num_core_configured, qc_num_core_reserved and qc_num_core_standby.
Note: Sum of qc_num_cp_total and qc_num_ifl_total might be smaller or larger, since some assists and spares are missing, and only the general purpose CPU type is considered
qc_num_core_configured int S   General purpose cores only without IFLs and zIIPs
qc_num_core_standby int S   General purpose cores which are in the (very brief) process of being added to the configuration
qc_num_core_reserved int S   IFLs, zIIPs, spares, excluding IFPs (Internal Firmware Processors)
qc_num_core_dedicated int  hV Sum of qc_num_cp_dedicated and qc_num_ifl_dedicated
Note: [4]
qc_num_core_shared int  hV Sum of qc_num_cp_shared and qc_num_ifl_shared
Note: [4]
qc_num_cp_total int  HV Equals the sum of qc_num_cp_dedicated and qc_num_cp_shared
Reported in unit of cores
Note: [4]
qc_num_cp_dedicated int  hV Reported in unit of cores
Note: [4]
qc_num_cp_shared int  hV Reported in unit of cores
Note: [4]
qc_num_ifl_total int  HV Equals the sum of qc_num_ifl_dedicated and qc_num_ifl_shared
Reported in unit of cores
Note: [4]
qc_num_ifl_dedicated int  hV Reported in unit of cores
Note: [4]
qc_num_ifl_shared int  hV Reported in unit of cores
Note: [4]
qc_num_ziip_total int  HV Equals the sum of qc_num_ziip_dedicated and qc_num_ziip_shared
Reported in unit of cores
Note: [4]
qc_num_ziip_dedicated int  hV Reported in unit of cores
Note: [4]
qc_num_ziip_shared int  hV Reported in unit of cores
Note: [4]
qc_num_cp_threads int S   Number of threads/CPUs per CP core that the CEC is capable of
Note: Requires Linux kernel 4.4 or higher
qc_num_ifl_threads int S   Number of threads/CPUs per IFL core that the CEC is capable of
Note: Requires Linux kernel 4.4 or higher
qc_num_ziip_threads int S   Number of threads/CPUs per zIIP core that the CEC is capable of
Note: Requires Linux kernel 4.4 or higher
qc_capability float S  
qc_secondary_capability float S  
qc_capacity_adjustment_indication int S  
qc_capacity_change_reason int S  
Attributes for LPAR Groups Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_LPAR_GROUP
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_POOL
qc_layer_type string Hardcoded to "LPAR-Group"
qc_layer_category string Hardcoded to "POOL"
qc_layer_name string  hV Name of LPAR group
qc_cp_absolute_capping int  hV Reported in unit of cores
qc_ifl_absolute_capping int  hV Reported in unit of cores
qc_ziip_absolute_capping int  hV Reported in unit of cores
Attributes for LPARs Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_LPAR
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_GUEST
qc_layer_type string Hardcoded to "LPAR"
qc_layer_category string Hardcoded to "GUEST"
qc_layer_name string S V Name of LPAR, limited to 8 characters
qc_layer_extended_name string S   Name of LPAR with up to 256 characters
Note: Requires Linux kernel 4.10 or higher
qc_layer_uuid string S   Note: Requires Linux kernel 4.10 or higher
qc_partition_number int S  
qc_partition_char string S  
qc_partition_char_num int S  
qc_adjustment int S  
qc_has_secure int F  
qc_secure int F  
qc_num_core_total int S Total number of CPs and IFLs configured in the LPARs activation profile
qc_num_core_configured int S   Note: [5]
qc_num_core_standby int S   Operational cores that require add'l configuration within the LPAR image to become usable
Note: [5]
qc_num_core_reserved int S   Operational cores that require add'l interaction by the LPAR's administrator to become usable
Note: [5]
qc_num_core_dedicated int S   Dedicated operational cores only
Note: [5], hence sum of qc_num_cp_dedicated, qc_num_ifl_dedicated and qc_num_ziip_dedicated can be larger
qc_num_core_shared int S   Shared operational cores only
Note: [5], hence sum of qc_num_cp_shared, qc_num_ifl_shared and qc_num_ziip_dedicated can be larger
qc_num_cp_total int  HV Sum of qc_num_cp_dedicated and qc_num_cp_shared. Considers configured CPs only.
Reported in unit of cores
qc_num_cp_dedicated int  hV Reported in unit of cores
qc_num_cp_shared int  hV Reported in unit of cores
qc_num_ifl_total int  HV Sum of qc_num_ifl_dedicated and qc_num_ifl_shared. Considers configured IFLs only.
Reported in unit of cores
qc_num_ifl_dedicated int  hV Reported in unit of cores
qc_num_ifl_shared int  hV Reported in unit of cores
qc_num_ziip_total int  HV Sum of qc_num_ziip_dedicated and qc_num_ziip_shared. Considers configured zIIPs only.
Reported in unit of cores
qc_num_ziip_dedicated int  hV Reported in unit of cores
qc_num_ziip_shared int  hV Reported in unit of cores
qc_num_cp_threads int S   Number of threads/CPUs per CP core configured for this LPAR
Note: Requires Linux kernel 4.3 or higher
qc_num_ifl_threads int S   Number of threads/CPUs per IFL core configured for this LPAR
Note: Requires Linux kernel 4.3 or higher
qc_num_ziip_threads int S   Number of threads/CPUs per zIIP core configured for this LPAR
Note: Requires Linux kernel 4.3 or higher
qc_cp_absolute_capping int  hV Reported in unit of cores
qc_cp_weight_capping int  hV Reported in unit of cores
Note: [4]
qc_ifl_absolute_capping int  hV Reported in unit of cores
qc_ifl_weight_capping int  hV Reported in unit of cores
Note: [4]
qc_ziip_absolute_capping int  hV Reported in unit of cores
qc_ziip_weight_capping int  hV Reported in unit of cores
Note: [4]
Attributes for z/VM hypervisors Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_ZVM_HYPERVISOR
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_HOST
qc_layer_type string Hardcoded to "z/VM-hypervisor"
qc_layer_category string Hardcoded to "HOST"
qc_layer_name string   V System identifier of the hypervisor
qc_cluster_name string   V
qc_control_program_id string S   ID of CP
qc_adjustment int S   Adjustment factor of z/VM
qc_limithard_consumption int   V
qc_prorated_core_time int   V
qc_num_core_total int   V Sum of qc_num_core_dedicated and qc_num_core_shared
qc_num_core_dedicated int   V Sum of qc_num_cp_dedicated and qc_num_ifl_dedicated
qc_num_core_shared int   V Sum of qc_num_cp_shared and qc_num_ifl_dedicated
qc_num_cp_total int   V Sum of qc_num_cp_dedicated and qc_num_cp_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_dedicated int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_shared int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ifl_total int   V Sum of qc_num_ifl_dedicated and qc_num_ifl_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ifl_dedicated int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ifl_shared int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ziip_total int   V Sum of qc_num_ziip_dedicated and qc_num_ziip_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ziip_shared int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ziip_dedicated int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_threads int   V Number of threads/CPUs per CP core in use
qc_num_ifl_threads int   V Number of threads/CPUs per IFL core in use
qc_num_ziip_threads int   V Number of threads/CPUs per zIIP core in use
Attributes for z/VM resource pools Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_ZVM_RESOURCE_POOL
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_POOL
qc_layer_type string Hardcoded to "z/VM-resource-pool", or "z/VM-CPU-pool" if compiled with CONFIG_V1_COMPATIBILITY
qc_layer_category string Hardcoded to "POOL"
qc_layer_name string   V Name of resource pool
qc_cp_limithard_cap int   V
qc_cp_capacity_cap int   V
qc_cp_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_ifl_limithard_cap int   V
qc_ifl_capacity_cap int   V
qc_ifl_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_ziip_limithard_cap int   V
qc_ziip_capacity_cap int   V
qc_ziip_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
Attributes for z/VM guests Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_ZVM_GUEST
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_GUEST
qc_layer_type string Hardcoded to "z/VM-guest"
qc_layer_category string Hardcoded to "GUEST"
qc_layer_name string S V Userid of guest
qc_capping string  H
qc_capping_num int  H
qc_mobility_enabled int   V
qc_has_secure int F  
qc_secure int F  
qc_num_cpu_total int S V Sum of qc_num_cpu_configured, qc_num_cpu_standby and qc_num_cpu_reserved, or qc_num_cpu_dedicated and qc_num_cpu_shared
qc_num_cpu_configured int S  
qc_num_cpu_standby int S  
qc_num_cpu_reserved int S  
qc_num_cpu_dedicated int  HV Sum of qc_num_cp_dedicated and qc_num_ifl_dedicated
qc_num_cpu_shared int  HV Sum of qc_num_cp_shared and qc_num_ifl_shared
qc_num_cp_total int   V Sum of qc_num_cp_dedicated and qc_num_cp_shared
Reported in unit of CPUs
qc_num_cp_dedicated int   V Reported in unit of CPUs
qc_num_cp_shared int   V Reported in unit of CPUs
qc_num_ifl_total int   V Sum of qc_num_ifl_dedicated and qc_num_ifl_shared
Reported in unit of CPUs
qc_num_ifl_dedicated int   V Reported in unit of CPUs
qc_num_ifl_shared int   V Reported in unit of CPUs
qc_num_ziip_total int   V Sum of qc_num_ziip_dedicated and qc_num_ziip_shared
Reported in unit of CPUs
qc_num_ziip_dedicated int   V Reported in unit of CPUs
qc_num_ziip_shared int   V Reported in unit of CPUs
qc_has_multiple_cpu_types int   V
qc_cp_dispatch_limithard int   V
qc_cp_dispatch_type int   V Only set in presence of CPs
qc_cp_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_ifl_dispatch_limithard int   V
qc_ifl_dispatch_type int   V Only set in presence of IFLs
qc_ifl_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_ziip_dispatch_limithard int   V
qc_ziip_dispatch_type int   V Only set in presence of zIIPs
qc_ziip_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
Attributes for z/OS hypervisors Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_ZOS_HYPERVISOR
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_HOST
qc_layer_type string Hardcoded to "z/OS-hypervisor"
qc_layer_category string Hardcoded to "HOST"
qc_layer_name string   V System identifier of the hypervisor
qc_cluster_name string   V Name of sysplex
qc_control_program_id string S   ID of z/OS
qc_adjustment int S   Adjustment factor of z/OS
qc_num_core_total int   V Sum of qc_num_core_dedicated and qc_num_core_shared
qc_num_core_dedicated int   V Sum of qc_num_cp_dedicated and qc_num_ziip_dedicated
qc_num_core_shared int   V Sum of qc_num_cp_shared and qc_num_ziip_shared
qc_num_cp_total int   V Sum of qc_num_cp_dedicated and qc_num_cp_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_dedicated int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_shared int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ziip_total int   V Sum of qc_num_ziip_dedicated and qc_num_ziip_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ziip_shared int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ziip_dedicated int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_threads int   V Number of threads/CPUs per CP core in use
qc_num_ziip_threads int   V Number of threads/CPUs per zIIP core in use
Attributes for z/OS resource groups Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_ZOS_TENANT_RESOURCE_GROUP
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_POOL
qc_layer_type string Hardcoded to "z/OS-tenant-resource-group"
qc_layer_category string Hardcoded to "POOL"
qc_layer_name string   V Name of resource group
qc_cp_limithard_cap int   V
qc_cp_capacity_cap int   V
qc_cp_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_ziip_limithard_cap int   V
qc_ziip_capacity_cap int   V
qc_ziip_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
Attributes for z/OS zCX Servers Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_ZOS_ZCX_SERVER
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_GUEST
qc_layer_type string Hardcoded to "z/OS-guest"
qc_layer_category string Hardcoded to "GUEST"
qc_layer_name string S V Userid of guest
qc_capping string  H
qc_capping_num int  H
qc_has_secure int F  
qc_secure int F  
qc_num_cpu_total int S V Sum of qc_num_cpu_configured, qc_num_cpu_standby and qc_num_cpu_reserved, or qc_num_cpu_dedicated and qc_num_cpu_shared
qc_num_cpu_configured int S  
qc_num_cpu_standby int S  
qc_num_cpu_reserved int S  
qc_num_cpu_dedicated int  HV Sum of qc_num_cp_dedicated and qc_num_ifl_dedicated
qc_num_cpu_shared int  HV Sum of qc_num_cp_shared and qc_num_ifl_shared
qc_num_cp_total int   V Sum of qc_num_cp_dedicated and qc_num_cp_shared
Reported in unit of CPUs
qc_num_cp_dedicated int   V Reported in unit of CPUs
qc_num_cp_shared int   V Reported in unit of CPUs
qc_num_ziip_total int   V Sum of qc_num_ziip_dedicated and qc_num_ziip_shared
Reported in unit of CPUs
qc_num_ziip_dedicated int   V Reported in unit of CPUs
qc_num_ziip_shared int   V Reported in unit of CPUs
qc_has_multiple_cpu_types int   V
qc_cp_dispatch_limithard int   V
qc_cp_dispatch_type int   V Only set in presence of CPs
qc_cp_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_ziip_dispatch_limithard int   V
qc_ziip_dispatch_type int   V Only set in presence of zIIPs
NOTE: I guess it would be cleaner if we would switch to IFL attributes instead of zIIPs, since that is (to my understanding), what Linux will see - and use THIS attribute to indicate that the IFLs are dispatched to zIIPs...?
qc_ziip_capped_capacity int   V Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
Attributes for KVM hypervisors Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_KVM_HYPERVISOR
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_HOST
qc_layer_type string Hardcoded to "KVM-hypervisor"
qc_layer_category string Hardcoded to "HOST"
qc_control_program_id string S   Host ID
qc_adjustment int S  
qc_num_core_total int S   Sum of qc_num_core_dedicated and qc_num_core_shared
qc_num_core_dedicated int SHV Sum of qc_num_cp_dedicated and qc_num_ifl_dedicated
qc_num_core_shared int SHV Sum of qc_num_cp_shared and qc_num_ifl_shared
qc_num_cp_total int  HV Sum of qc_num_cp_dedicated and qc_num_cp_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_dedicated int  hV Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_cp_shared int  hV Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ifl_total int SHV Sum of qc_num_ifl_dedicated and qc_num_ifl_shared
Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ifl_dedicated int ShV Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
qc_num_ifl_shared int ShV Reported in unit of cores unless run as a guest of another hypervisor other than LPAR
Attributes for KVM guests Type Src Comment
qc_layer_type_num int Hardcoded to QC_LAYER_TYPE_KVM_GUEST
qc_layer_category_num int Hardcoded to QC_LAYER_CAT_GUEST
qc_layer_type string Hardcoded to "KVM-guest"
qc_layer_category string Hardcoded to "GUEST"
qc_layer_name string S   Guest name truncated to 8 characters
Note: [1]
qc_layer_extended_name string S   Guest name with up to 256 characters
Note: Requires Linux kernel 3.19 or higher, [1]
qc_layer_uuid string S   Note: Requires Linux kernel 3.19 or higher
qc_has_secure int F  
qc_secure int F  
qc_num_cpu_total int S   Sum of qc_num_cpu_configured, qc_num_cpu_standby and qc_num_cpu_reserved, or qc_num_cpu_dedicated and qc_num_cpu_shared
qc_num_cpu_configured int S  
qc_num_cpu_standby int S  
qc_num_cpu_reserved int S  
qc_num_cpu_dedicated int S  
qc_num_cpu_shared int S  
qc_num_ifl_total int S   Sum of qc_num_ifl_dedicated and qc_num_ifl_shared
Reported in unit of CPUs
qc_num_ifl_dedicated int S   Reported in unit of CPUs
qc_num_ifl_shared int S   Reported in unit of CPUs
qc_ifl_dispatch_type int SHV

[1] Available starting with RHEL7.2 and SLES12SP1
[2] z/Architecture Principles of Operation, SA22-7832
[3] z/VM: CP Commands and Utilities Reference, SC24-6175
[4] Requires global performance data (GDP) to be enabled in the LPAR's activation profile
[5] As of this writing, in LPARs with both CPs and IFLs defined in its activation profile, only CPs can become operational. Therefore, IFL counts would not appear in any of qc_num_core_configured, qc_num_core_standby, qc_num_core_reserved, qc_num_core_dedicated or qc_num_core_shared

Enumerator
qc_adjustment 

The adjustment factor indicates the maximum percentage of the machine (in parts of 1000) that could be used by the primary processor type in the worst case by the respective layer, taking cappings and other limiting factors into consideration.
Note: This value can lead to wrong conclusions for layers that utilize more than one processor type!

qc_capability 

Capability rating, see STSI instruction in [2]

qc_capacity_adjustment_indication 

Capacity adjustment value, see STSI instruction in [2]

qc_capacity_change_reason 

Reason for capacity adjustment, see STSI instruction in [2]

qc_capping 

Capping type: "off", "soft", "hard"

qc_capping_num 

Numeric representation of capping type, see enum qc_cappings

qc_cluster_name 

SSI name if part of SSI cluster

qc_control_program_id 

ID of control program

qc_cp_absolute_capping 

CP absolute capping value. Scaled value where 0x10000 equals to one core, or 0 if no capping set

qc_cp_capacity_cap 

1 if pool's CP virtual type has capped capacity
0 if not
See DEFINE CPUPOOL command in [3]

qc_cp_capped_capacity 

Guest current capped capacity for shared virtual CPs – scaled value where 0x10000 equals to one core, or 0 if no capping set. While this field displays the capacity, either qc_cp_capacity_cap or qc_cp_limithard_cap must is set to indicate the kind of limit.

qc_cp_dispatch_limithard 

1 if guest CP dispatch type has LIMITHARD capping,
0 if not
See SET SRM command in [3]

qc_cp_dispatch_type 

Dispatch type for guest CPs:
0=General Purpose (CP)

qc_cp_limithard_cap 

1 if pool's CP virtual type has limithard capping
0 if not
See DEFINE CPUPOOL command in [3]

qc_cp_weight_capping 

CP weight-based capping value – scaled value where 0x10000 equals to one core, or 0 if no capping set

qc_limithard_consumption 

1 if SRM limithard setting is consumption
0 if deadline
See SET SRM command in [3]

qc_has_multiple_cpu_types 

1 if layer has multiple CPU types (e.g. CPs, IFLs, zIIPs),
0 if not

qc_ifl_absolute_capping 

IFL absolute capping value – scaled value where 0x10000 equals to one core, or 0 if no capping set

qc_ifl_capacity_cap 

1 if pool's IFL virtual type has capped capacity
0 if not
See DEFINE CPUPOOL command in [3]

qc_ifl_capped_capacity 

Guest current capped capacity for shared virtual IFLs – scaled value where 0x10000 equals to one core, or 0 if no capping set. While this field displays the capacity, either qc_ifl_capacity_cap or qc_ifl_limithard_cap must is set to indicate the kind of limit.

qc_ifl_dispatch_limithard 

1 if guest IFL dispatch type has LIMITHARD capping,
0 if not
See SET SRM command in [3]

qc_ifl_dispatch_type 

Dispatch type for guest IFLs:
0=General Purpose (CP),
3=Integrated Facility for Linux (IFL)

qc_ifl_limithard_cap 

1 if pool's IFL virtual type has limithard capping
0 if not
See DEFINE CPUPOOL command in [3]

qc_ifl_weight_capping 

IFL weight-based capping value – scaled value where 0x10000 equals to one core, or 0 if no capping set

qc_ziip_absolute_capping 

zIIP absolute capping value – scaled value where 0x10000 equals to one core, or 0 if no capping set

qc_ziip_capacity_cap 

1 if pool's zIIP virtual type has capped capacity
0 if not
See DEFINE CPUPOOL command in [3]

qc_ziip_capped_capacity 

Guest current capped capacity for shared virtual zIIPs – scaled value where 0x10000 equals to one core, or 0 if no capping set. While this field displays the capacity, either qc_ziip_capacity_cap or qc_ziip_limithard_cap must is set to indicate the kind of limit.

qc_ziip_dispatch_limithard 

1 if guest zIIP dispatch type has LIMITHARD capping,
0 if not
See SET SRM command in [3]

qc_ziip_dispatch_type 

Dispatch type for guest zIIPs:
0=General Purpose (CP),
5=zSeries Integrated Information Processor (zIIP),
ff=zIIP or CP

qc_ziip_limithard_cap 

1 if pool's zIIP virtual type has limithard capping
0 if not
See DEFINE CPUPOOL command in [3]

qc_ziip_weight_capping 

zIIP weight-based capping value – scaled value where 0x10000 equals to one core, or 0 if no capping set

qc_layer_category 

Layer category, see layer tables above for details

qc_layer_category_num 

Numeric representation of layer category, see enum qc_layer_categories

qc_layer_extended_name 

Guest extended name

qc_layer_name 

Name of container, see layer tables for details

qc_layer_type 

Layer type, see layer tables above for details

qc_layer_type_num 

Numeric representation of layer type, see enum qc_layer_types

qc_layer_uuid 

Universal unique ID

qc_manufacturer 

Company that manufactured box

qc_mobility_enabled 

1 if guest is enabled for mobility,
0 if not

qc_has_secure 

Indicates whether secure boot is available to the entity. Requires Linux kernel 5.3 or later. Note: This attribute is only ever available for the topmost layer.

qc_secure 

Indicates whether entity was booted using the secure boot feature Requires Linux kernel 5.3 or later. Note: This attribute is only ever available for the topmost layer.

qc_model 

Model identifier, see STSI instruction in [2]

qc_model_capacity 

Model capacity of machine, see STSI instruction in [2]

qc_type_family 

Family of the model, enum qc_model_families

qc_num_cp_dedicated 

Sum of dedicated CPs in layer

qc_num_cp_shared 

Sum of shared CPs in layer

qc_num_cp_total 

Sum of all CPs in layer

qc_num_cpu_configured 

Sum of configured CPs and IFLs in layer

qc_num_cpu_dedicated 

Sum of dedicated CPs and IFLs in layer

qc_num_cpu_reserved 

Sum of reserved CPs and IFLs in layer

qc_num_cpu_shared 

Sum of shared CPs and IFLs in layer

qc_num_cpu_standby 

Sum of standby CPs and IFLs in layer

qc_num_cpu_total 

Sum of all CPs and IFLs in layer

qc_num_ifl_dedicated 

Sum of dedicated IFLs in layer

qc_num_ifl_shared 

Sum of shared IFLs in layer

qc_num_ifl_total 

Sum of all IFLs (Integrated Facility for Linux) in layer

qc_num_ziip_dedicated 

Sum of dedicated zIIPs in layer

qc_num_ziip_shared 

Sum of shared zIIPs in layer

qc_num_ziip_total 

Sum of all zIIPs (Integrated Information Processor) in layer

qc_partition_char 

Partition characteristics, any combination of "Dedicated", "Shared" and "Limited", also see STSI instruction in [2]

qc_partition_char_num 

Numeric representation of partition characteristics, see enum qc_part_chars

qc_partition_number 

Partition number, see STSI instruction in [2]

qc_plant 

Identifier of the manufacturing plant, see STSI instruction in [2]

qc_secondary_capability 

Secondary capability rating, see STSI instruction in [2]

qc_sequence_code 

Sequence code of machine, see STSI instruction in [2]

qc_type 

4-digit machine type

qc_prorated_core_time 

1 if limithard caps uses prorated core time for capping
0 if raw CPU time is used
See APAR VM65680

qc_num_cp_threads 

Threads per CP, values >1 indicate that SMT is enabled

qc_num_ifl_threads 

Threads per IFL, values >1 indicate that SMT is enabled

qc_num_ziip_threads 

Threads per zIIP, values >1 indicate that SMT is enabled

qc_num_core_total 

Sum of all CP and IFL cores in layer

qc_num_core_configured 

Sum of configure CP and IFL cores in layer

qc_num_core_standby 

Sum of standby CP and IFL cores in layer

qc_num_core_reserved 

Sum of reserved CP and IFL cores in layer

qc_num_core_dedicated 

Sum of dedicated CP and IFL cores in layer

qc_num_core_shared 

Sum of shared CP and IFL cores in layer

qc_type_name 

Name of IBM Z model in clear text

qc_lic_identifier 

Licensed Internal Code (LIC) level

◆ qc_cappings

Numeric representation of the capping type, see qc_capping.

Enumerator
QC_CAPPING_OFF 

Capping turned off

◆ qc_layer_categories

Layer categories.

Enumerator
QC_LAYER_CAT_GUEST 

Layer category for guests, namely LPARs, z/VM and KVM guests

QC_LAYER_CAT_HOST 

Layer category for hosts, namely CEC, z/VM and KVM hosts

QC_LAYER_CAT_POOL 

Layer category for pools (currently z/VM Pools and LPAR capping groups)

◆ qc_layer_types

Enumerator
QC_LAYER_TYPE_CEC 

CEC

QC_LAYER_TYPE_LPAR_GROUP 

LPAR Capping Group

QC_LAYER_TYPE_LPAR 

LPAR

QC_LAYER_TYPE_ZVM_HYPERVISOR 

z/VM Hypervisor

QC_LAYER_TYPE_ZVM_CPU_POOL 

z/VM CPU Pool (deprecated, use QC_LAYER_TYPE_ZVM_RESOURCE_POOL instead)

QC_LAYER_TYPE_ZVM_RESOURCE_POOL 

z/VM Resource Pool

QC_LAYER_TYPE_ZVM_GUEST 

z/VM Guest

QC_LAYER_TYPE_KVM_HYPERVISOR 

KVM Hypervisor

QC_LAYER_TYPE_KVM_GUEST 

KVM Guest

QC_LAYER_TYPE_ZOS_HYPERVISOR 

z/OS Hypervisor

QC_LAYER_TYPE_ZOS_TENANT_RESOURCE_GROUP 

z/OS Tenant Resource Group

QC_LAYER_TYPE_ZOS_ZCX_SERVER 

z/OS cCX Server

◆ qc_model_families

Enumerator
QC_TYPE_FAMILY_IBMZ 

IBM Z

QC_TYPE_FAMILY_LINUXONE 

LinuxONE

◆ qc_part_chars

Characteristic of an an LPAR.

Enumerator
QC_PART_CHAR_DEDICATED 

LPAR has dedicated resources

QC_PART_CHAR_SHARED 

LPAR shares resources with other LPARs

QC_PART_CHAR_LIMITED 

LPAR has limited resources

Function Documentation

◆ qc_close()

void qc_close ( void *  hdl)

Closes the configuration handle and releases all memory allocated when the configuration was opened. The configuration handle is invalid after calling this function, as are any returned pointers of previous capacity function calls.

If logging or autodumping was enabled on qc_open(), environment variables QC_DEBUG and QC_AUTODUMP need to be set to integers <=0 on the final call to qc_close() (or whenever neither functionality is not required anymore) to correctly free up all resources.

Parameters
hdlHandle of the configuration to close.

◆ qc_export_json()

void qc_export_json ( void *  hdl)

Prints the internal data in JSON format to stdout.

Parameters
hdlHandle of the configuration to use.

◆ qc_get_attribute_float()

int qc_get_attribute_float ( void *  hdl,
enum qc_attr_id  id,
int  layer,
float *  value 
)

Returns the attribute of type float designated by id. If the attribute is not available at the specified layer, the attribute is not of type float, or another error occurred, return parameter valid will be set accordingly.

See also
qc_get_attribute_string()
qc_get_attribute_int()
Parameters
hdlHandle of the configuration to use.
idAttribute to retrieve.
layerSpecifies the layer, e.g.
  • 0: CEC layer information,
  • 1: LPAR layer information, etc.
valueReturn parameter returning the float attribute's value or undefined in case of an error.indicating validity as follows:
Returns
Indicating validity of the queried attribute as follows:
  • >0 attribute is valid
  • 0 attribute exists but is not set
  • <0 an error occurred retrieving the attribute

◆ qc_get_attribute_int()

int qc_get_attribute_int ( void *  hdl,
enum qc_attr_id  id,
int  layer,
int *  value 
)

Returns the attribute of type integer designated by id. If the attribute is not available at the specified layer, the attribute is not of type integer, or another error occurred, return parameter valid will be set accordingly.

See also
qc_get_attribute_string()
qc_get_attribute_float()
Parameters
hdlHandle of the configuration to use.
idAttribute to retrieve.
layerSpecifies the layer, e.g.
  • 0: CEC layer information,
  • 1: LPAR layer information, etc.
valueReturn parameter returning the string attribute's value or undefined in case of an error.
Returns
Indicating validity of the queried attribute as follows:
  • >0 attribute is valid
  • 0 attribute exists but is not set
  • <0 an error occurred retrieving the attribute

◆ qc_get_attribute_string()

int qc_get_attribute_string ( void *  hdl,
enum qc_attr_id  id,
int  layer,
const char **  value 
)

Returns the attribute of type string designated by id. If the attribute is not available at the specified layer, the attribute is not of type string, or another error occurred, return parameter valid will be set accordingly.

See also
qc_get_attribute_int()
qc_get_attribute_float()
Parameters
hdlHandle of the configuration to use.
idAttribute to retrieve.
layerSpecifies the layer, e.g.
  • 0: CEC layer information,
  • 1: LPAR layer information, etc.
valueReturn parameter returning the string attribute's value or NULL in case of an error.
Returns
Indicating validity of the queried attribute as follows:
  • >0 attribute is valid
  • 0 attribute exists but is not set
  • <0 an error occurred retrieving the attribute

◆ qc_get_num_layers()

int qc_get_num_layers ( void *  hdl,
int *  rc 
)

Get the number of layers.

Parameters
hdlHandle of the configuration to use.
rcReturn parameter indicating the return code. Set to
  • 0 on success,
  • <0 in case of an error.
Returns
Number of layer. E.g.
  • 2 if Linux runs in an LPAR
  • 4 if a z/VM guest runs in a z/VM Hypervisor in an LPAR, or
  • 5 if a z/VM guest runs in a capping group in z/VM running in LPAR.

◆ qc_open()

void* qc_open ( int *  rc)

Attaches to system information sources and prepares the extraction of system information. Some information may be gathered at this time already: under LPAR, /proc/sysinfo is read and interpreted; under z/VM, *VMINFO data is read using the STHYI instruction (requires z/VM 6.3 with APAR VM65419, or higher). Capacity queries then take place based on this information which could be considered cached.
Memory will be allocated in this function, which has to be released by closing the configuration again. While a configuration is open, SSI migration in z/VM is not blocked and can occur. In case a migration occurs after a configuration has been opened, closing the configuration and re-opening it ensures capacity information is used from the migrated-to system.
Use the following environment variables to operate built-in service facilities:

  • QC_DEBUG: Set to an integer value
    • >0 to enable logging to a file /tmp/qclib-XXXXXX or as specified by QC_DEBUG_FILE if set.
    • >1 to have data dumped to a directory named <STEM>.dump-XXX on every qc_open() call (where STEM is /tmp/qclib-XXXXXX or as specified by QC_DEBUG_FILE if set.
      To disable logging, either see qc_close(), or set QC_DEBUG to a value <=0 on the next qc_open() call.
  • QC_DEBUG_FILE: Stem to use for log files and dump directories (see QC_DEBUG). Defaults to /tmp/qclib-XXXXXX.
  • QC_AUTODUMP: Set to a value >0 to trigger a dump to a directory named /tmp/qclib-XXXXXX.dump-XXX if an error is encountered within qc_open().
    Note: This will also create an empty log file for technical reasons, unless QC_DEBUG was set to a value >0
  • QC_USE_DUMP: To run with a previously generated dump instead of live data, point this environment variable to a directory containing the dump data. Requires compilation with CONFIG_DUMP_READING set.
  • QC_CHECK_CONSISTENCY: Check data for consistency. Recommended for debugging scenarios only.
See also
qc_close()
Parameters
rcReturn parameter indicating the return code. Set to
  • 0 on success,
  • <0 in case of an error, and
  • >0 if the configuration could not be read completely at the moment, but a retry later on could provide the missing data.
Returns
Returns a configuration handle which is valid for reading out capacity data until the configuration is closed. Returns NULL in case of an error.