|
| 1 | + qclib (Query Capacity Library) |
| 2 | + ============================== |
| 3 | + |
| 4 | +qclib provides a C API for extraction of system information for Linux on IBM Z. |
| 5 | + |
| 6 | +For instance, it will provide the number of CPUs |
| 7 | + * on the machine (CEC, Central Electronic Complex) layer |
| 8 | + * on the PR/SM (Processor Resource/Systems Manager) layer, i.e. visible to |
| 9 | + LPARs, including LPAR groups |
| 10 | + * in z/VM hosts, guests and CPU pools |
| 11 | + * in KVM hosts and guests |
| 12 | +This allows calculating the upper limit of CPU resources a highest level guest |
| 13 | +can use. |
| 14 | +E.g.: If an LPAR on a z13 provides 4 CPUs to a z/VM hypervisor, and the |
| 15 | +hypervisor provides 8 virtual CPUs to a guest, qclib can be used to retrieve |
| 16 | +all of these numbers, and it can be concluded that not more capacity than 4 |
| 17 | +CPUs can be used by the software running in the guest. |
| 18 | + |
| 19 | +qclib uses various interfaces and provides this data through a common and |
| 20 | +consistent API (Application Programming Interface), using information provided |
| 21 | +by: |
| 22 | + * STSI (Store System Information) instruction - for more details, refer to |
| 23 | + the z/Architecture Principles of Operation (SA22-7832) |
| 24 | + * STHYI (Store Hypervisor Information) instruction as provided by a z/VM |
| 25 | + hypervisor - for more information, refer to z/VM: V6R3 CP Programming |
| 26 | + Service (SC24-6179), chapter 'Store Hypervisor Information (STHYI) |
| 27 | + Instruction'. |
| 28 | + * hypfs file system - for more information, refer to 'Device Drivers, |
| 29 | + Features, and Commands', chapter 'S/390 hypervisor file system'. |
| 30 | + * Firmware interface /sys/firmware/ocf - for more information, refer to |
| 31 | + 'Device Drivers, Features, and Commands', chapter 'Identifying the z |
| 32 | + Systems hardware'. |
| 33 | + |
| 34 | +Please refer to: |
| 35 | + http://www.ibm.com/developerworks/linux/linux390/qclib.html |
| 36 | +for the latest available version. |
| 37 | + |
| 38 | + |
| 39 | +Usage |
| 40 | +===== |
| 41 | +See query_capacity.h for details on how to use the API, and qc_test.c for a |
| 42 | +sample program. |
| 43 | + |
| 44 | + |
| 45 | +Requirements |
| 46 | +============ |
| 47 | +See query_capacity.h for details. |
| 48 | + |
| 49 | + |
| 50 | +Build |
| 51 | +===== |
| 52 | +Use the following 'make' targets: |
| 53 | + * 'all' (default): Build static and dynamic libraries, as well as respective |
| 54 | + sample programs 'qc_test' (statically linked) and 'qc_test-sh' |
| 55 | + (dynamically linked). |
| 56 | + * 'test': Build and run the statically linked test program qc_test. |
| 57 | + Note: Requires a static version of glibc, which some |
| 58 | + distributions do not install per default. |
| 59 | + * 'test-sh': Build and run the dynamically linked test program qc_test. |
| 60 | + |
| 61 | + |
| 62 | +API Documentation |
| 63 | +================= |
| 64 | +All documentation is available in file query_capacity.h. |
| 65 | +If you have doxygen 1.8.6 (or higher) installed, you will find the |
| 66 | +documentation in subdirectory html, after using 'make doc'. |
| 67 | + |
| 68 | + |
| 69 | +License |
| 70 | +======= |
| 71 | +See enclosed file LICENSE for details. |
| 72 | + |
| 73 | + |
| 74 | +Bug Reports |
| 75 | +=========== |
| 76 | +See section 'Code Contributions'. |
| 77 | + |
| 78 | + |
| 79 | +Code Contributions |
| 80 | +================== |
| 81 | +Code contributions will not be accepted for qclib. |
| 82 | +Therefore, please do not send DIFFs or code-snippets. Thank you! |
| 83 | +If you want to report bugs or suggest enhancements, please contact: |
| 84 | + |
| 85 | +and put "[qclib]" as the first word in the subject line of your mail. |
| 86 | +For bug reports, at a minimum attach a log file and a dump (see QC_DEBUG as |
| 87 | +described in query_capacity.h or, yet better, use the qc_dump utility), and |
| 88 | +describe the scenario in which you observed the bug, so that the problem can |
| 89 | +be reproduced. |
| 90 | +For enhancements, please describe the proposed change and its benefits. |
| 91 | + |
| 92 | + |
| 93 | +Release History: |
| 94 | +================ |
| 95 | + |
| 96 | +2.0.0 |
| 97 | + Changes: |
| 98 | + - Add support for z/OS Container Extensions (zCX) |
| 99 | + - New attributes in layer CEC: |
| 100 | + * qc_type_name |
| 101 | + * qc_type_family |
| 102 | + * qc_lic_identifier |
| 103 | + - qc_test: Reworked output for subtle consistency improvements |
| 104 | + - Replaced attribute qc_hardlimit_consumption with |
| 105 | + qc_limithard_consumption. Use CONFIG_V1_COMPATIBILITY for previous |
| 106 | + version. |
| 107 | + - Require CONFIG_DUMP_READING in query_capacity.h to allow running from a |
| 108 | + dump. Disabled by default. |
| 109 | + - Disabled v1 compatibility functionality per default. To re-enable, |
| 110 | + activate CONFIG_V1_COMPATIBILITY in query_capacity.h. |
| 111 | + |
| 112 | +1.4.1 |
| 113 | + Bug fixes: |
| 114 | + - qc_dump: Don't abort the dump in case qc_test fails. |
| 115 | + - Attributes qc_cp_weight_capping and qc_ifl_weight_capping were set even |
| 116 | + when initial capping was not set in the LPAR's activation profile. |
| 117 | + |
| 118 | +1.4.0 |
| 119 | + Changes: |
| 120 | + - Added SMT support by properly differentiating between cores and CPUs. |
| 121 | + I.e. switched from qc_num_cpu_* to qc_num_core_* attributes in layers |
| 122 | + CEC, LPAR, ZVM_HYPERVISOR and KVM_HYPERVISOR. |
| 123 | + NOTE: qc_num_cpu_* attributes remain to be valid in these cases to |
| 124 | + preserve backwards compatibility for now. This will be removed in |
| 125 | + one of the next releases! It is recommended to switch to the new |
| 126 | + attributes _now_ and test with CONFIG_V1_COMPATIBILITY disabled! |
| 127 | + - Added new attributes qc_num_threads_cp and qc_num_threads_ifl to layers |
| 128 | + CEC, LPAR and ZVM_HYPERVISOR. |
| 129 | + - Deprecated attribute qc_mobility_eligible (remains valid for now) and |
| 130 | + replaced with qc_mobility_enabled to match z/VM terminology. Likewise |
| 131 | + switched QC_LAYER_TYPE_ZVM_CPU_POOL to QC_LAYER_TYPE_ZVM_RESOURCE_POOL. |
| 132 | + - Moved build customization defines (e.g. CONFIG_V1_COMPATIBILITY) to |
| 133 | + query_capacity.h. |
| 134 | + - Don't build with textual hypfs per default anymore due to unrecoverable |
| 135 | + issues (see section 'Bug fixes'). Since all Linux distributions ship |
| 136 | + with debugfs (providing binary hypfs support), overriding textual hypfs, |
| 137 | + for years, this change will hardly ever be noticable. Enable define |
| 138 | + CONFIG_TEXTUAL_HYPFS in query_capacity.h to revert. |
| 139 | + Note that textual hypfs support will be removed in a future release. |
| 140 | + |
| 141 | + Bug fixes: |
| 142 | + - Added an exception to consistency check to ignore inconsistencies between |
| 143 | + textual hypfs and STHYI for attributes qc_num_cp_total and |
| 144 | + qc_num_ifl_total in the LPAR layer. |
| 145 | + Background: Textual hypfs cannot tell whether a core is configured or |
| 146 | + not. It therefore reports all cores as configured, which can |
| 147 | + be wrong. |
| 148 | + |
| 149 | +1.3.1 |
| 150 | + Bug fixes: |
| 151 | + - Security: Fix PATH attack vulnerability when dumping (see QC_DEBUG=2) |
| 152 | + - STHYI: Add fallback for pre-glibc 2.16 (not using getauxval()) |
| 153 | + - Handle mismatching STHYI and /proc/sysinfo layer counts |
| 154 | + - On LPAR, fix incomplete dump of binary hypfs when textual hypfs is mounted |
| 155 | + |
| 156 | +1.3.0 |
| 157 | + Changes: |
| 158 | + - Added STHYI support in LPAR |
| 159 | + - Added new env variable QC_DEBUG_FILE (see qc_open()) |
| 160 | + Note: Failure to open a file for logging is now treated as a fatal error |
| 161 | + - Added script qc_dump to collect debug data in a standardized manner |
| 162 | + - Added attributes qc_layer_uuid and qc_layer_extended_name to LPAR layer |
| 163 | + - /proc/sysinfo parsing: Switch from "KVM/Linux" to the less strict "KVM" |
| 164 | + to detect KVM systems |
| 165 | + - Detect unregistered and closed handles |
| 166 | + - Makefile: Compile SONAME into shared library |
| 167 | + |
| 168 | + Bug fixes: |
| 169 | + - STHYI: Properly support cc==3&&rc==4 as introduced in APAR VM65419 |
| 170 | + - Logs: Fix month in timestamp (was off by 1) |
| 171 | + - qc_test: Fix flags for qc_layer_name in QC_LAYER_TYPE_ZVM_HYPERVISOR |
| 172 | + |
| 173 | +1.2.0 |
| 174 | + Changes: |
| 175 | + - Removed source [S] for attributes qc_num_cpu_dedicated and |
| 176 | + qc_num_cpu_shared in LPAR layer for consistency |
| 177 | + - Retrieve qc_layer_name in CEC layer from OCF |
| 178 | + - Extended hypfs usage to provide more CP, IFL and CPU counts for |
| 179 | + CEC and LPAR layers, as well as capping information for LPAR group |
| 180 | + and LPAR layers |
| 181 | + - Added attributes for IFLs, CPs and CPUs for KVM hypervisor and guest |
| 182 | + layers |
| 183 | + - Added support for LPAR Groups |
| 184 | + - Added new attribute qc_prorated_core_time |
| 185 | + - Fill qc_num_cp_total and qc_num_ifl_total in LPAR layer from STHYI |
| 186 | + - Consistency checks: Detect inconsistent values across data sources |
| 187 | + - Documentation improvements |
| 188 | + |
| 189 | + Bug fixes: |
| 190 | + - Fixed crash when setting QC_USE_DUMP to an invalid directory and |
| 191 | + QC_DEBUG=1 |
| 192 | + - Fixed reset of debug level when QC_CHECK_CONSISTENCY is invalid |
| 193 | + - Display all values in attribute qc_partition_char in case of multiple |
| 194 | + - Set qc_cp_dispatch_type in presence of CPs only |
| 195 | + |
| 196 | +1.1.0 |
| 197 | + Changes: |
| 198 | + - Makefile: Added targets 'clean' and 'install' |
| 199 | + - qc_test: Support command line options |
| 200 | + - Performance improvements |
| 201 | + - Consistency checks: Turned into a run-time option. Disabled per |
| 202 | + default, enabled in qc_test |
| 203 | + |
| 204 | + Bug fixes: |
| 205 | + - Makefile: Fixed breakages, including when run in verbose mode |
| 206 | + - Fixed handling of hostnames with <8 characters in presence of hypfs |
| 207 | + - If no SSI cluster was present, attribute qc_cluster_name was set |
| 208 | + to an empty string instead of being left undefined |
| 209 | + - Consistency checks: Fixed wrong positive |
| 210 | + - Fixed source indicators in log |
| 211 | + |
| 212 | +1.0.0 |
| 213 | + Changes: |
| 214 | + - Introduced new API, replacing the previous one |
| 215 | + - Renamed the following attributes for consistency: |
| 216 | + * qc_container_name became qc_layer_name |
| 217 | + * qc_entity_* became qc_layer_* |
| 218 | + - Introduced the following new attributes for a numeric representation |
| 219 | + of the respective string attributes: |
| 220 | + * qc_layer_type_num (alternative to qc_layer_type) |
| 221 | + * qc_layer_category_num (alternative to qc_layer_category) |
| 222 | + * qc_partition_char_num (alternative to qc_partition_char) |
| 223 | + * qc_capping_num (alternative to qc_capping) |
| 224 | + - Removed/renamed the following attributes, since they were duplicates of |
| 225 | + other layers' content: |
| 226 | + * In layer type QC_LAYER_TYPE_ZVM_GUEST: Removed qc_hyp_*, qc_pool_* |
| 227 | + qc_system_identifier, qc_cluster_name, qc_control_program_id, |
| 228 | + qc_adjustment, and qc_hardlimit_consumption |
| 229 | + * In layer type QC_LAYER_TYPE_ZVM_CPU_POOL: Removed qc_hyp_*, |
| 230 | + qc_system_identifier, qc_cluster_name, qc_hardlimit_consumption, and |
| 231 | + renamed qc_pool_* to qc_* |
| 232 | + - Added support for KVM hypervisor |
| 233 | + - Added logging facility |
| 234 | + - Added dump support: Capability to create and run on dumps |
| 235 | + - Added autodump support: Create dumps on errors only |
| 236 | + - Added doxygen support for API description in query_capacity.h |
| 237 | + - Added support for hypfs mounted at arbitrary locations |
| 238 | + - Added support for binary hypfs API (requires RHEL6.1 and SLES11.2 or |
| 239 | + higher) |
| 240 | + - Added detection of Live Guest Migration while retrieving data |
| 241 | + - Handled NULL pointer arguments in all API calls |
| 242 | + - Reported errors as such when occurring while searching for capacity |
| 243 | + information |
| 244 | + |
| 245 | + Bug fixes: |
| 246 | + - Handled file access errors |
| 247 | + - Enabled attributes that were incorrectly indicated as not present |
| 248 | + - Fixed qc_get_num_layers() to return the number of layers (as documented), |
| 249 | + not the highest index |
| 250 | + - Fixed race by reading /proc/sysinfo only once |
| 251 | + - Only set qc_ifl_dispatch_type in presence of IFLs (as intended) |
| 252 | + |
| 253 | +0.9.2 |
| 254 | + Bug fixes: |
| 255 | + - Fixed memory leaks |
| 256 | + |
| 257 | +0.9.1 |
| 258 | + Bug fixes: |
| 259 | + - Fixed crash with more than 1 layers of nested z/VM virtualization |
| 260 | + - Fixed crash on 1st layer z/VM systems with hypfs |
| 261 | + - Fix: Information from /proc/sysinfo was collected in wrong sequence |
| 262 | + with more than 1 layers of nested virtualization |
| 263 | + - Fixed left open file handles in hypfs parsing code. |
| 264 | + - Added consistency check for hypfs |
| 265 | + |
| 266 | +0.9.0 |
| 267 | + Initial version |
| 268 | + |
| 269 | + |
| 270 | + |
| 271 | +Copyright IBM Corp. 2013, 2018 |
0 commit comments