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_