1 /* 2 * Copyright (c) 2012-2014 Apple Computer, Inc. All Rights Reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29 #ifndef _IOREPORT_TYPES_H_ 30 #define _IOREPORT_TYPES_H_ 31 32 #include <stdint.h> 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 #define IOR_VALUES_PER_ELEMENT 4 39 40 /*! @const kIOReportInvalidValue 41 * @const kIOReportInvalidIntValue 42 * @abstract cardinal value used to indicate data errors 43 * 44 * @discussion 45 * kIOReportInvalidValue and kIOReportInvalidIntValue have the 46 * same bit pattern so that clients checking for one or the other 47 * don't have to worry about getting the signedness right. 48 */ 49 #define kIOReportInvalidIntValue INT64_MIN 50 #define kIOReportInvalidValue (uint64_t)kIOReportInvalidIntValue 51 52 /*! @typedef IOReportCategories 53 * @abstract encapsulate important, multi-purpose "tags" for channels 54 * 55 * @discussion 56 * IOReportCategories is the type for the .categories field of 57 * IOReportChanelType. These categories are inteded to empower a 58 * limited number of clients to retrieve a broad range of channels 59 * without knowing much about them. They can be OR'd together as 60 * needed. Groups and subgroups are a more extensible mechanism 61 * for aggregating channels produced by different drivers. 62 */ 63 typedef uint16_t IOReportCategories; 64 #define kIOReportCategoryPower (1 << 1) // and energy 65 #define kIOReportCategoryTraffic (1 << 2) // I/O at any level 66 #define kIOReportCategoryPerformance (1 << 3) // e.g. cycles/byte 67 #define kIOReportCategoryPeripheral (1 << 4) // not built-in 68 69 #define kIOReportCategoryField (1 << 8) // consider logging 70 71 // future categories TBD 72 #define kIOReportCategoryDebug (1 << 15) 73 #define kIOReportInvalidCategory UINT16_MAX 74 75 76 // IOReportChannelType.report_format 77 typedef uint8_t IOReportFormat; 78 enum { 79 kIOReportInvalidFormat = 0, 80 kIOReportFormatSimple = 1, 81 kIOReportFormatState = 2, 82 kIOReportFormatHistogram = 3, 83 kIOReportFormatSimpleArray = 4 84 }; 85 86 // simple report values 87 typedef struct { 88 int64_t simple_value; 89 uint64_t reserved1; 90 uint64_t reserved2; 91 uint64_t reserved3; 92 } __attribute((packed)) IOSimpleReportValues; 93 94 // simple value array 95 typedef struct { 96 int64_t simple_values[IOR_VALUES_PER_ELEMENT]; 97 } __attribute((packed)) IOSimpleArrayReportValues; 98 99 // state report values 100 typedef struct { 101 uint64_t state_id; // 0..N-1 or 8-char code (see MAKEID()) 102 uint64_t intransitions; // number of transitions into this state 103 uint64_t upticks; // ticks spent in state (local timebase) 104 uint64_t last_intransition;// ticks at last in-transition 105 } __attribute((packed)) IOStateReportValues; 106 107 // histogram report values 108 typedef struct { 109 uint64_t bucket_hits; 110 int64_t bucket_min; 111 int64_t bucket_max; 112 int64_t bucket_sum; 113 } __attribute((packed)) IOHistogramReportValues; 114 115 116 117 // configuration actions generally change future behavior 118 typedef uint32_t IOReportConfigureAction; 119 enum { 120 // basics (in common operational order) 121 kIOReportEnable = 0x01, 122 kIOReportGetDimensions = 0x02, 123 kIOReportDisable = 0x00, 124 125 // Enable/disable modifiers 126 kIOReportNotifyHubOnChange = 0x10, // triggered polling 127 128 kIOReportTraceOnChange = 0x20 // kdebug.h tracing 129 }; 130 131 // update actions should not have observable side effects 132 typedef uint32_t IOReportUpdateAction; 133 enum { 134 kIOReportCopyChannelData = 1, 135 kIOReportTraceChannelData = 2 136 }; 137 138 typedef struct { 139 uint8_t report_format; // Histogram, StateResidency, etc. 140 uint8_t reserved; // must be zero 141 uint16_t categories; // power, traffic, etc (omnibus obs.) 142 uint16_t nelements; // internal size of channel 143 144 // only meaningful in the data pipeline 145 int16_t element_idx; // 0..nelements-1 146 // -1..-(nelements) = invalid (13127884) 147 } __attribute((packed)) IOReportChannelType; 148 149 /*! 150 * @define IOREPORT_MAKECHID 151 * @abstract convert up to 8 printable characters into a 64-bit channel ID 152 * @param <char0..char7> - printable chars to be packed into a channel ID 153 * @result a 64-bit channel ID with an implicit ASCII name 154 * @discussion A simple example: 155 * IOREPORT_MAKECHID('H', 'i', ' ', 'w', 'o', 'r', 'l', 'd'); 156 * will evaluate to 0x686920776f726c64. Any NUL bytes are 157 * ignored (by libIOReport) for naming purposes, but will 158 * appear in the channel ID. Using a non-NUL non-printable 159 * character will disable the implicit name. Putting NUL 160 * bytes first eliminates trailing zeros when the channel 161 * ID is printed as hex. For example: 162 * IORERPORT_MAKECHID('\0','\0','n','x','f','e','r','s'); 163 * To see the text, use xxd -r -p # not -rp; see 12976241 164 */ 165 #define __IOR_lshiftchr(c, chshift) ((uint64_t)(c) << (8*(chshift))) 166 #define IOREPORT_MAKEID(A, B, C, D, E, F, G, H) \ 167 (__IOR_lshiftchr(A, 7) | __IOR_lshiftchr(B, 6) | __IOR_lshiftchr(C, 5) \ 168 | __IOR_lshiftchr(D, 4) | __IOR_lshiftchr(E, 3) | __IOR_lshiftchr(F, 2) \ 169 | __IOR_lshiftchr(G, 1) | __IOR_lshiftchr(H, 0)) 170 171 typedef struct { 172 uint64_t channel_id; 173 IOReportChannelType channel_type; 174 } IOReportChannel; 175 176 typedef struct { 177 uint32_t nchannels; 178 IOReportChannel channels[]; 179 } IOReportChannelList; 180 181 typedef struct { 182 uint64_t provider_id; 183 IOReportChannel channel; 184 } IOReportInterest; 185 186 typedef struct { 187 uint32_t ninterests; 188 IOReportInterest interests[]; 189 } IOReportInterestList; 190 191 typedef struct { 192 uint64_t v[IOR_VALUES_PER_ELEMENT]; 193 } __attribute((packed)) IOReportElementValues; 194 195 typedef struct { 196 uint64_t provider_id; 197 uint64_t channel_id; 198 IOReportChannelType channel_type; 199 uint64_t timestamp;// mach_absolute_time() 200 IOReportElementValues values; 201 } __attribute((packed)) IOReportElement; 202 203 204 205 /* 206 * IOReporting unit type and constants 207 */ 208 209 // 1. Mechanism 210 211 // Assume encoded units could be stored in binary format: don't 212 // change existing values. 213 214 typedef uint64_t IOReportUnit; 215 typedef uint64_t IOReportUnits; // deprecated typo, please switch 216 #define __IOR_MAKEUNIT(quantity, scale) \ 217 (((IOReportUnit)quantity << 56) | (uint64_t)scale) 218 #define IOREPORT_GETUNIT_QUANTITY(unit) \ 219 ((IOReportQuantity)((uint64_t)unit >> 56) & 0xff) 220 #define IOREPORT_GETUNIT_SCALE(unit) \ 221 ((IOReportScaleFactor)unit & 0x00ffffffffffffff) 222 223 // 8b quantity ID | 32b const val + 8b*2^10 + 8b*2^n | 8b cardinal | 8b unused 224 typedef uint8_t IOReportQuantity; // SI "quantity" is what's measured 225 typedef uint64_t IOReportScaleFactor; 226 227 // See <http://en.wikipedia.org/wiki/SI_base_unit> for a list 228 // of quantities and their symbols. 229 enum { 230 // used by state reports, etc 231 kIOReportQuantityUndefined = 0, 232 233 kIOReportQuantityTime = 1,// Seconds 234 kIOReportQuantityPower = 2,// Watts 235 kIOReportQuantityEnergy = 3,// Joules 236 kIOReportQuantityCurrent = 4,// Amperes 237 kIOReportQuantityVoltage = 5,// Volts 238 kIOReportQuantityCapacitance = 6,// Farad 239 kIOReportQuantityInductance = 7,// Henry 240 kIOReportQuantityFrequency = 8,// Hertz 241 kIOReportQuantityData = 9,// bits/bytes (see scale) 242 kIOReportQuantityTemperature = 10,// Celsius (not Kelvin :) 243 244 kIOReportQuantityEventCount = 100, 245 kIOReportQuantityPacketCount = 101, 246 kIOReportQuantityCPUInstrs = 102 247 }; 248 249 250 /* A number of units end up with both IEC (2^n) and SI (10^n) scale factors. 251 * For example, the "MB" of a 1.44 MB floppy or a 1024MHz clock. We 252 * thus support separate 2^n and 10^n factors. The exponent encoding 253 * scheme is modeled loosely on single-precision IEEE 754. 254 */ 255 #define kIOReportScaleConstMask 0x000000007fffffff // constant ("uint31") 256 #define kIOReportScaleOneOver (1LL << 31) // 1/constant 257 #define kIOReportExpBase (-127) // support base^(-n) 258 #define kIOReportExpZeroOffset -(kIOReportExpBase) // max exponent = 128 259 #define kIOReportScaleSIShift 32 // * 10^n 260 #define kIOReportScaleSIMask 0x000000ff00000000 261 #define kIOReportScaleIECShift 40 // * 2^n 262 #define kIOReportScaleIECMask 0x0000ff0000000000 263 #define kIOReportCardinalShift 48 // placeholders 264 #define kIOReportCardinalMask 0x00ff000000000000 265 266 267 /* 268 * Scales are described as a factor times unity: 269 * 1ms = kIOReportScaleMilli * s 270 * 271 * A value expressed in a scaled unit can be scaled to unity via 272 * multiplication by the constant: 273 * 100ms * kIOReportScaleMilli [1e-3] = 0.1s. 274 */ 275 276 // SI / decimal 277 #define kIOReportScalePico ((-12LL + kIOReportExpZeroOffset) \ 278 << kIOReportScaleSIShift) 279 #define kIOReportScaleNano ((-9LL + kIOReportExpZeroOffset) \ 280 << kIOReportScaleSIShift) 281 #define kIOReportScaleMicro ((-6LL + kIOReportExpZeroOffset) \ 282 << kIOReportScaleSIShift) 283 #define kIOReportScaleMilli ((-3LL + kIOReportExpZeroOffset) \ 284 << kIOReportScaleSIShift) 285 #define kIOReportScaleUnity 0 // 10^0 = 2^0 = 1 286 // unity = 0 is a special case for which we give up exp = -127 287 #define kIOReportScaleKilo ((3LL + kIOReportExpZeroOffset) \ 288 << kIOReportScaleSIShift) 289 #define kIOReportScaleMega ((6LL + kIOReportExpZeroOffset) \ 290 << kIOReportScaleSIShift) 291 #define kIOReportScaleGiga ((9LL + kIOReportExpZeroOffset) \ 292 << kIOReportScaleSIShift) 293 #define kIOReportScaleTera ((12LL + kIOReportExpZeroOffset) \ 294 << kIOReportScaleSIShift) 295 296 // IEC / computer / binary 297 // It's not clear we'll ever use 2^(-n), but 1..2^~120 should suffice. 298 #define kIOReportScaleBits kIOReportScaleUnity 299 #define kIOReportScaleBytes ((3LL + kIOReportExpZeroOffset) \ 300 << kIOReportScaleIECShift) 301 // (bytes have to be added to the exponents up front, can't just OR in) 302 #define kIOReportScaleKibi ((10LL + kIOReportExpZeroOffset) \ 303 << kIOReportScaleIECShift) 304 #define kIOReportScaleKiBytes ((13LL + kIOReportExpZeroOffset) \ 305 << kIOReportScaleIECShift) 306 #define kIOReportScaleMebi ((20LL + kIOReportExpZeroOffset) \ 307 << kIOReportScaleIECShift) 308 #define kIOReportScaleMiBytes ((23LL + kIOReportExpZeroOffset) \ 309 << kIOReportScaleIECShift) 310 #define kIOReportScaleGibi ((30LL + kIOReportExpZeroOffset) \ 311 << kIOReportScaleIECShift) 312 #define kIOReportScaleGiBytes ((33LL + kIOReportExpZeroOffset) \ 313 << kIOReportScaleIECShift) 314 #define kIOReportScaleTebi ((40LL + kIOReportExpZeroOffset) \ 315 << kIOReportScaleIECShift) 316 #define kIOReportScaleTiBytes ((43LL + kIOReportExpZeroOffset) \ 317 << kIOReportScaleIECShift) 318 // can't encode more than 2^125 (keeping bits & bytes inside -126..128) 319 // Also, IOReportScaleValue() is currently limited internally by uint64_t. 320 321 322 // Cardinal values, to be filled in appropriately. 323 // Add values in increasing order. 324 #define kIOReportScaleMachHWTicks (1LL << kIOReportCardinalShift) 325 #define kIOReportScaleHWPageSize (2LL << kIOReportCardinalShift) 326 327 // page scales: 2 pages * 4ikB/page = 8096 bytes 328 #define kIOReportScale4KiB (4 | kIOReportScaleKiBytes) 329 #define kIOReportScale8KiB (8 | kIOReportScaleKiBytes) 330 #define kIOReportScale16KiB (16 | kIOReportScaleKiBytes) 331 332 // Clock frequency scales (units add seconds). 333 // 1 GHz ticks are 1 ns: 1000 ticks * 1e-6 = 1e-3s 334 // This '1' is a no-op for scaling, but allows a custom label. 335 #define kIOReportScale1GHz (1 | kIOReportScaleNano) 336 // 24MHz ticks are 1/24 of a microsecond: (1/24 * kIOReportScaleMicro [1e-6])s 337 // So for example, 240 24Mticks * 1/24 * 1e-6 = .00001s [1e-5]s 338 #define kIOReportScale24MHz (kIOReportScaleOneOver|24 |kIOReportScaleMicro) 339 340 // --- END: units mechanism 341 342 343 // 2. Unit constants 344 #define kIOReportUnitNone __IOR_MAKEUNIT(kIOReportQuantityUndefined, \ 345 kIOReportScaleUnity) 346 347 #define kIOReportUnit_s __IOR_MAKEUNIT(kIOReportQuantityTime, \ 348 kIOReportScaleUnity) 349 #define kIOReportUnit_ms __IOR_MAKEUNIT(kIOReportQuantityTime, \ 350 kIOReportScaleMilli) 351 #define kIOReportUnit_us __IOR_MAKEUNIT(kIOReportQuantityTime, \ 352 kIOReportScaleMicro) 353 #define kIOReportUnit_ns __IOR_MAKEUNIT(kIOReportQuantityTime, \ 354 kIOReportScaleNano) 355 356 #define kIOReportUnit_J __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ 357 kIOReportScaleUnity) 358 #define kIOReportUnit_mJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ 359 kIOReportScaleMilli) 360 #define kIOReportUnit_uJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ 361 kIOReportScaleMicro) 362 #define kIOReportUnit_nJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ 363 kIOReportScaleNano) 364 #define kIOReportUnit_pJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ 365 kIOReportScalePico) 366 367 #define kIOReportUnitHWTicks __IOR_MAKEUNIT(kIOReportQuantityTime, \ 368 kIOReportScaleMachHWTicks) 369 #define kIOReportUnit24MHzTicks __IOR_MAKEUNIT(kIOReportQuantityTime, \ 370 kIOReportScale24MHz) 371 #define kIOReportUnit1GHzTicks __IOR_MAKEUNIT(kIOReportQuantityTime, \ 372 kIOReportScale1GHz) 373 374 #define kIOReportUnitBits __IOR_MAKEUNIT(kIOReportQuantityData, \ 375 kIOReportScaleBits) 376 #define kIOReportUnitBytes __IOR_MAKEUNIT(kIOReportQuantityData, \ 377 kIOReportScaleBytes) 378 #define kIOReportUnit_KiB __IOR_MAKEUNIT(kIOReportQuantityData, \ 379 kIOReportScaleKiBytes) 380 #define kIOReportUnit_MiB __IOR_MAKEUNIT(kIOReportQuantityData, \ 381 kIOReportScaleMiBytes) 382 #define kIOReportUnit_GiB __IOR_MAKEUNIT(kIOReportQuantityData, \ 383 kIOReportScaleGiBytes) 384 #define kIOReportUnit_TiB __IOR_MAKEUNIT(kIOReportQuantityData, \ 385 kIOReportScaleTiBytes) 386 387 #define kIOReportUnitEvents __IOR_MAKEUNIT(kIOReportQuantityEventCount, \ 388 kIOReportScaleUnity) 389 390 #define kIOReportUnitPackets __IOR_MAKEUNIT(kIOReportQuantityPacketCount, \ 391 kIOReportScaleUnity) 392 393 #define kIOReportUnitInstrs __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ 394 kIOReportScaleUnity) 395 #define kIOReportUnit_KI __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ 396 kIOReportScaleKilo) 397 #define kIOReportUnit_MI __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ 398 kIOReportScaleMega) 399 #define kIOReportUnit_GI __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ 400 kIOReportScaleGiga) 401 402 // Please file bugs (xnu | IOReporting) for additional units. 403 404 // --- END: unit constants 405 406 407 #ifdef __cplusplus 408 } 409 #endif 410 411 #endif // _IOREPORT_TYPES_H_ 412