iokit/IOKit/IOKernelReportStructs.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 // Internal data structures to be used by IOReporters and User Space Observers
  30
  31
  32 #ifndef _IOKERNELREPORTSTRUCTS_H_
  33 #define _IOKERNELREPORTSTRUCTS_H_
  34
  35 #include <stdint.h>
  36
  37 #include <IOKit/IOReportTypes.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 #define kIOReportAPIVersion 28
  44
  45 // Drivers participating in IOReporting can advertise channels by
  46 // publishing properties in the I/O Kit registry.  Various helper
  47 // mechanisms exist to produce correctly-formatted legends.
  48 // 12836893 tracks declaring channels in user space.
  49 #define kIOReportLegendPublicKey        "IOReportLegendPublic"      // bool
  50 #define kIOReportLegendKey              "IOReportLegend"            // arr
  51 #define kIOReportLegendChannelsKey      "IOReportChannels"          // arr
  52 #define kIOReportLegendGroupNameKey     "IOReportGroupName"         // str
  53 #define kIOReportLegendSubGroupNameKey  "IOReportSubGroupName"      // str
  54 #define kIOReportLegendInfoKey          "IOReportChannelInfo"       // dict
  55 #define kIOReportLegendUnitKey          "IOReportChannelUnit"       // num
  56 #define kIOReportLegendConfigKey        "IOReportChannelConfig"     // data
  57 #define kIOReportLegendStateNamesKey    "IOReportChannelStateNames" // str[]
  58
  59 // in an I/O Kit registry legend, a small "array struct" represents a channel
  60 #define kIOReportChannelIDIdx           0       // required
  61 #define kIOReportChannelTypeIdx         1       // required
  62 #define kIOReportChannelNameIdx         2       // optional
  63
  64 // We are currently (internally) limited to 15 (broad!) categories.
  65
  66
  67 /*
  68    Units / Scaling Factors
  69
  70    1. Implementation Details
  71    2. Unit Constants (kIOReportUnit...) for clients
  72
  73    Please file radars if you need more units (IOReporting | X)
  74 */
  75
  76 // 1. Implementation Details
  77 // We are likely to someday support IOReporting data as stored binary data.
  78 // Don't change existing values lest that data become unreadable.
  79
  80 typedef uint64_t IOReportUnits;
  81 #define __IOR_MAKEUNIT(quantity, scale) \
  82         (((IOReportUnits)quantity << 56) | (uint64_t)scale)
  83 #define IOREPORT_GETUNIT_QUANTITY(unit) \
  84         ((IOReportQuantity)((uint64_t)unit >> 56) & 0xff)
  85 #define IOREPORT_GETUNIT_SCALE(unit) \
  86         ((IOReportScaleFactor)unit & 0x00ffffffffffffff)
  87
  88 // 8b quantity + 32b const + 8b * 2^10 + 8b * 2^n + 8b cardinal + 8b unused
  89 typedef uint8_t IOReportQuantity;       // SI "quantity" is what's measured
  90 typedef uint64_t IOReportScaleFactor;
  91
  92 // See <http://en.wikipedia.org/wiki/SI_base_unit> for a list
  93 // of quantities and their symbols.
  94 enum {
  95     // used by state reports, etc
  96     kIOReportQuantityUndefined = 0,
  97
  98     kIOReportQuantityTime = 1,          // Seconds
  99     kIOReportQuantityPower = 2,         // Watts
 100     kIOReportQuantityEnergy = 3,        // Joules
 101     kIOReportQuantityCurrent = 4,       // Amperes
 102     kIOReportQuantityVoltage = 5,       // Volts
 103     kIOReportQuantityCapacitance = 6,   // Farad
 104     kIOReportQuantityInductance = 7,    // Henry
 105     kIOReportQuantityFrequency = 8,     // Hertz
 106     kIOReportQuantityData = 9,          // bits/bytes (see scale)
 107     kIOReportQuantityTemperature = 10,  // Celsius (not Kelvin :)
 108
 109     kIOReportQuantityEventCount = 100,
 110     kIOReportQuantityPacketCount = 101
 111 };
 112
 113
 114 /* A number of units end up with both IEC (2^n) and SI (10^n) scale factors.
 115    For example, the "MB" of a 1.44 MB floppy or a 1024MHz clock.  We
 116    thus support separate 2^n and 10^n factors.  The exponent encoding
 117    scheme is modeled loosely on single-precision IEEE 754.
 118  */
 119 #define kIOReportScaleConstMask 0x000000007fffffff      // constant ("uint31")
 120 #define kIOReportScaleOneOver   (1LL << 31)             // 1/constant
 121 #define kIOReportExpBase        (-127)                  // support base^(-n)
 122 #define kIOReportExpZeroOffset  -(kIOReportExpBase)     // max exponent = 128
 123 #define kIOReportScaleSIShift   32                      // * 10^n
 124 #define kIOReportScaleSIMask    0x000000ff00000000
 125 #define kIOReportScaleIECShift  40                      // * 2^n
 126 #define kIOReportScaleIECMask   0x0000ff0000000000
 127 #define kIOReportCardinalShift  48                      // placeholders
 128 #define kIOReportCardinalMask   0x00ff000000000000
 129
 130
 131 /*
 132    Scales are described as a factor times unity:
 133    1ms = kIOReportScaleMilli * s
 134
 135    A value expressed in a scaled unit can be scaled to unity via
 136    multiplication by the constant:
 137    100ms * kIOReportScaleMilli [1e-3] = 0.1s.
 138 */
 139
 140 // SI / decimal
 141 #define kIOReportScalePico  ((-12LL + kIOReportExpZeroOffset)  \
 142                                         << kIOReportScaleSIShift)
 143 #define kIOReportScaleNano  ((-9LL + kIOReportExpZeroOffset)  \
 144                                         << kIOReportScaleSIShift)
 145 #define kIOReportScaleMicro ((-6LL + kIOReportExpZeroOffset)  \
 146                                         << kIOReportScaleSIShift)
 147 #define kIOReportScaleMilli ((-3LL + kIOReportExpZeroOffset)  \
 148                                         << kIOReportScaleSIShift)
 149 #define kIOReportScaleUnity 0    // 10^0 = 2^0 = 1
 150 // unity = 0 is a special case for which we give up exp = -127
 151 #define kIOReportScaleKilo  ((3LL + kIOReportExpZeroOffset)  \
 152                                         << kIOReportScaleSIShift)
 153 #define kIOReportScaleMega  ((6LL + kIOReportExpZeroOffset)  \
 154                                         << kIOReportScaleSIShift)
 155 #define kIOReportScaleGiga  ((9LL + kIOReportExpZeroOffset)  \
 156                                         << kIOReportScaleSIShift)
 157 #define kIOReportScaleTera  ((12LL + kIOReportExpZeroOffset)  \
 158                                         << kIOReportScaleSIShift)
 159
 160 // IEC / computer / binary
 161 // It's not clear we'll ever use 2^(-n), but 1..2^~120 should suffice.
 162 #define kIOReportScaleBits  kIOReportScaleUnity
 163 #define kIOReportScaleBytes     ((3LL + kIOReportExpZeroOffset)  \
 164                                             << kIOReportScaleIECShift)
 165 // (bytes have to be added to the exponents up front, can't just OR in)
 166 #define kIOReportScaleKibi      ((10LL + kIOReportExpZeroOffset)  \
 167                                             << kIOReportScaleIECShift)
 168 #define kIOReportScaleKiBytes   ((13LL + kIOReportExpZeroOffset)  \
 169                                             << kIOReportScaleIECShift)
 170 #define kIOReportScaleMebi      ((20LL + kIOReportExpZeroOffset)  \
 171                                             << kIOReportScaleIECShift)
 172 #define kIOReportScaleMiBytes   ((23LL + kIOReportExpZeroOffset)  \
 173                                             << kIOReportScaleIECShift)
 174 #define kIOReportScaleGibi      ((30LL + kIOReportExpZeroOffset)  \
 175                                             << kIOReportScaleIECShift)
 176 #define kIOReportScaleGiBytes   ((33LL + kIOReportExpZeroOffset)  \
 177                                             << kIOReportScaleIECShift)
 178 #define kIOReportScaleTebi      ((40LL + kIOReportExpZeroOffset)  \
 179                                             << kIOReportScaleIECShift)
 180 #define kIOReportScaleTiBytes   ((43LL + kIOReportExpZeroOffset)  \
 181                                             << kIOReportScaleIECShift)
 182 // can't encode more than 2^125 (keeping bits & bytes inside -126..128)
 183 // Also, IOReportScaleValue() is currently limited internally by uint64_t.
 184
 185
 186 // Cardinal values, to be filled in appropriately.
 187 // Add values in increasing order.
 188 #define kIOReportScaleMachHWTicks   (1LL << kIOReportCardinalShift)
 189 #define kIOReportScaleHWPageSize    (2LL << kIOReportCardinalShift)
 190
 191 // page scales: 2 pages * 4ikB/page = 8096 bytes
 192 #define kIOReportScale4KiB      (4 | kIOReportScaleKiBytes)
 193 #define kIOReportScale8KiB      (8 | kIOReportScaleKiBytes)
 194
 195 // Clock frequencies scales (units add seconds).
 196 // 1 GHz ticks are 1 ns: 1000 ticks * 1e-6 = 1e-3s
 197 // The '1' is a no-op, but allows a custom label.
 198 #define kIOReportScale1GHz      (1 | kIOReportScaleNano)
 199 // 24MHz ticks are 1/24 of a microsecond: (1/24 * kIOReportScaleMicro [1e-6])s
 200 // So for example, 240 24Mticks * 1/24 * 1e-6 = .00001s [1e-5]s
 201 #define kIOReportScale24MHz     (kIOReportScaleOneOver|24 |kIOReportScaleMicro)
 202
 203 // --- END: implementation details
 204
 205 // 2. Units Constants
 206 // --- BEGIN: units constants driver writers might use
 207 #define kIOReportUnitNone       __IOR_MAKEUNIT(kIOReportQuantityUndefined,  \
 208                                                   kIOReportScaleUnity)
 209
 210 #define kIOReportUnit_s         __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 211                                                kIOReportScaleUnity)
 212 #define kIOReportUnit_ms        __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 213                                                kIOReportScaleMilli)
 214 #define kIOReportUnit_us        __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 215                                                kIOReportScaleMicro)
 216 #define kIOReportUnit_ns        __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 217                                                kIOReportScaleNano)
 218
 219 #define kIOReportUnit_J         __IOR_MAKEUNIT(kIOReportQuantityEnergy,  \
 220                                                kIOReportScaleUnity)
 221 #define kIOReportUnit_mJ        __IOR_MAKEUNIT(kIOReportQuantityEnergy,  \
 222                                                kIOReportScaleMilli)
 223 #define kIOReportUnit_uJ        __IOR_MAKEUNIT(kIOReportQuantityEnergy,  \
 224                                                kIOReportScaleMicro)
 225 #define kIOReportUnit_nJ        __IOR_MAKEUNIT(kIOReportQuantityEnergy,  \
 226                                                kIOReportScaleNano)
 227 #define kIOReportUnit_pJ        __IOR_MAKEUNIT(kIOReportQuantityEnergy,  \
 228                                                kIOReportScalePico)
 229
 230 #define kIOReportUnitHWTicks    __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 231                                                kIOReportScaleMachHWTicks)
 232 #define kIOReportUnit24MHzTicks __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 233                                                kIOReportScale24MHz)
 234 #define kIOReportUnit1GHzTicks  __IOR_MAKEUNIT(kIOReportQuantityTime,  \
 235                                                kIOReportScale1GHz)
 236
 237 #define kIOReportUnitBits       __IOR_MAKEUNIT(kIOReportQuantityData,  \
 238                                                 kIOReportScaleBits)
 239 #define kIOReportUnitBytes      __IOR_MAKEUNIT(kIOReportQuantityData,  \
 240                                                 kIOReportScaleBytes)
 241 #define kIOReportUnit_KiB       __IOR_MAKEUNIT(kIOReportQuantityData,  \
 242                                                kIOReportScaleKiBytes)
 243 #define kIOReportUnit_MiB       __IOR_MAKEUNIT(kIOReportQuantityData,  \
 244                                                kIOReportScaleMiBytes)
 245 #define kIOReportUnit_GiB       __IOR_MAKEUNIT(kIOReportQuantityData,  \
 246                                                kIOReportScaleGiBytes)
 247 #define kIOReportUnit_TiB       __IOR_MAKEUNIT(kIOReportQuantityData,  \
 248                                                kIOReportScaleTiBytes)
 249
 250 #define kIOReportUnitEvents     __IOR_MAKEUNIT(kIOReportQuantityEventCount,  \
 251                                                kIOReportScaleUnity)
 252
 253 #define kIOReportUnitPackets    __IOR_MAKEUNIT(kIOReportQuantityPacketCount,  \
 254                                                kIOReportScaleUnity)
 255
 256 // Please file radars if you need more units (IOReporting | X)
 257
 258 // --- END: unit constants driver writers might use
 259
 260 /*  Histogram Segment Configuration
 261     Currently supports 2 types of scaling to compute bucket upper bounds,
 262     linear or exponential.
 263     scale_flag = 0 -> linear scale
 264                  1 -> exponential scale
 265     upper_bound[n] = (scale_flag) ? pow(base,(n+1)) : base * (n+1);
 266 */
 267 #define kIOHistogramScaleLinear 0
 268 #define kIOHistogramScaleExponential 1
 269 typedef struct {
 270     uint32_t    base_bucket_width;    // segment[0].bucket[0] = [0, base_width]
 271     uint32_t    scale_flag;           // bit 0 only in current use (see #defs)
 272     uint32_t    segment_idx;          // for multiple segments histograms
 273     uint32_t    segment_bucket_count; // number of buckets in this segment
 274 } __attribute((packed)) IOHistogramSegmentConfig;
 275
 276 // "normalized distribution"(FIXME?) internal format (unused?)
 277 typedef struct {
 278     uint64_t    samples;
 279     uint64_t    mean;
 280     uint64_t    variance;
 281     uint64_t    reserved;
 282 } __attribute((packed)) IONormDistReportValues;
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif // _IOKERNELREPORTSTRUCTS_H_