iokit/IOKit/IOReportTypes.h

   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_