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 40extern "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 80typedef 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 89typedef uint8_t IOReportQuantity; // SI "quantity" is what's measured 90typedef uint64_t IOReportScaleFactor; 91 92// See <http://en.wikipedia.org/wiki/SI_base_unit> for a list 93// of quantities and their symbols. 94enum { 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 244#define kIOReportUnitEvents __IOR_MAKEUNIT(kIOReportQuantityEventCount, \ 245 kIOReportScaleUnity) 246 247#define kIOReportUnitPackets __IOR_MAKEUNIT(kIOReportQuantityPacketCount, \ 248 kIOReportScaleUnity) 249 250// Please file radars if you need more units (IOReporting | X) 251 252// --- END: unit constants driver writers might use 253 254/* Histogram Segment Configuration 255 Currently supports 2 types of scaling to compute bucket upper bounds, 256 linear or exponential. 257 scale_flag = 0 -> linear scale 258 1 -> exponential scale 259 upper_bound[n] = (scale_flag) ? pow(base,(n+1)) : base * (n+1); 260*/ 261#define kIOHistogramScaleLinear 0 262#define kIOHistogramScaleExponential 1 263typedef struct { 264 uint32_t base_bucket_width; // segment[0].bucket[0] = [0, base_width] 265 uint32_t scale_flag; // bit 0 only in current use (see #defs) 266 uint32_t segment_idx; // for multiple segments histograms 267 uint32_t segment_bucket_count; // number of buckets in this segment 268} __attribute((packed)) IOHistogramSegmentConfig; 269 270// "normalized distribution"(FIXME?) internal format (unused?) 271typedef struct { 272 uint64_t samples; 273 uint64_t mean; 274 uint64_t variance; 275 uint64_t reserved; 276} __attribute((packed)) IONormDistReportValues; 277 278#ifdef __cplusplus 279} 280#endif 281 282#endif // _IOKERNELREPORTSTRUCTS_H_ 283