/* * Copyright (c) 2012-2014 Apple Computer, Inc. All Rights Reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ #ifndef _IOREPORT_TYPES_H_ #define _IOREPORT_TYPES_H_ #include #ifdef __cplusplus extern "C" { #endif #define IOR_VALUES_PER_ELEMENT 4 /*! @const kIOReportInvalidValue * @const kIOReportInvalidIntValue * @abstract cardinal value used to indicate data errors * * @discussion * kIOReportInvalidValue and kIOReportInvalidIntValue have the * same bit pattern so that clients checking for one or the other * don't have to worry about getting the signedness right. */ #define kIOReportInvalidIntValue INT64_MIN #define kIOReportInvalidValue (uint64_t)kIOReportInvalidIntValue /*! @typedef IOReportCategories * @abstract encapsulate important, multi-purpose "tags" for channels * * @discussion * IOReportCategories is the type for the .categories field of * IOReportChanelType. These categories are inteded to empower a * limited number of clients to retrieve a broad range of channels * without knowing much about them. They can be OR'd together as * needed. Groups and subgroups are a more extensible mechanism * for aggregating channels produced by different drivers. */ typedef uint16_t IOReportCategories; #define kIOReportCategoryPower (1 << 1) // and energy #define kIOReportCategoryTraffic (1 << 2) // I/O at any level #define kIOReportCategoryPerformance (1 << 3) // e.g. cycles/byte #define kIOReportCategoryPeripheral (1 << 4) // not built-in #define kIOReportCategoryField (1 << 8) // consider logging // future categories TBD #define kIOReportCategoryDebug (1 << 15) #define kIOReportInvalidCategory UINT16_MAX // IOReportChannelType.report_format typedef uint8_t IOReportFormat; enum { kIOReportInvalidFormat = 0, kIOReportFormatSimple = 1, kIOReportFormatState = 2, kIOReportFormatHistogram = 3, kIOReportFormatSimpleArray = 4 }; // simple report values typedef struct { int64_t simple_value; uint64_t reserved1; uint64_t reserved2; uint64_t reserved3; } __attribute((packed)) IOSimpleReportValues; // simple value array typedef struct { int64_t simple_values[IOR_VALUES_PER_ELEMENT]; } __attribute((packed)) IOSimpleArrayReportValues; // state report values typedef struct { uint64_t state_id; // 0..N-1 or 8-char code (see MAKEID()) uint64_t intransitions; // number of transitions into this state uint64_t upticks; // ticks spent in state (local timebase) uint64_t last_intransition;// ticks at last in-transition } __attribute((packed)) IOStateReportValues; // histogram report values typedef struct { uint64_t bucket_hits; int64_t bucket_min; int64_t bucket_max; int64_t bucket_sum; } __attribute((packed)) IOHistogramReportValues; // configuration actions generally change future behavior typedef uint32_t IOReportConfigureAction; enum { // basics (in common operational order) kIOReportEnable = 0x01, kIOReportGetDimensions = 0x02, kIOReportDisable = 0x00, // Enable/disable modifiers kIOReportNotifyHubOnChange = 0x10, // triggered polling kIOReportTraceOnChange = 0x20 // kdebug.h tracing }; // update actions should not have observable side effects typedef uint32_t IOReportUpdateAction; enum { kIOReportCopyChannelData = 1, kIOReportTraceChannelData = 2 }; typedef struct { uint8_t report_format; // Histogram, StateResidency, etc. uint8_t reserved; // must be zero uint16_t categories; // power, traffic, etc (omnibus obs.) uint16_t nelements; // internal size of channel // only meaningful in the data pipeline int16_t element_idx; // 0..nelements-1 // -1..-(nelements) = invalid (13127884) } __attribute((packed)) IOReportChannelType; /*! * @define IOREPORT_MAKECHID * @abstract convert up to 8 printable characters into a 64-bit channel ID * @param - printable chars to be packed into a channel ID * @result a 64-bit channel ID with an implicit ASCII name * @discussion A simple example: * IOREPORT_MAKECHID('H', 'i', ' ', 'w', 'o', 'r', 'l', 'd'); * will evaluate to 0x686920776f726c64. Any NUL bytes are * ignored (by libIOReport) for naming purposes, but will * appear in the channel ID. Using a non-NUL non-printable * character will disable the implicit name. Putting NUL * bytes first eliminates trailing zeros when the channel * ID is printed as hex. For example: * IORERPORT_MAKECHID('\0','\0','n','x','f','e','r','s'); * To see the text, use xxd -r -p # not -rp; see 12976241 */ #define __IOR_lshiftchr(c, chshift) ((uint64_t)(c) << (8*(chshift))) #define IOREPORT_MAKEID(A, B, C, D, E, F, G, H) \ (__IOR_lshiftchr(A, 7) | __IOR_lshiftchr(B, 6) | __IOR_lshiftchr(C, 5) \ | __IOR_lshiftchr(D, 4) | __IOR_lshiftchr(E, 3) | __IOR_lshiftchr(F, 2) \ | __IOR_lshiftchr(G, 1) | __IOR_lshiftchr(H, 0)) typedef struct { uint64_t channel_id; IOReportChannelType channel_type; } IOReportChannel; typedef struct { uint32_t nchannels; IOReportChannel channels[]; } IOReportChannelList; typedef struct { uint64_t provider_id; IOReportChannel channel; } IOReportInterest; typedef struct { uint32_t ninterests; IOReportInterest interests[]; } IOReportInterestList; typedef struct { uint64_t v[IOR_VALUES_PER_ELEMENT]; } __attribute((packed)) IOReportElementValues; typedef struct { uint64_t provider_id; uint64_t channel_id; IOReportChannelType channel_type; uint64_t timestamp;// mach_absolute_time() IOReportElementValues values; } __attribute((packed)) IOReportElement; /* * IOReporting unit type and constants */ // 1. Mechanism // Assume encoded units could be stored in binary format: don't // change existing values. typedef uint64_t IOReportUnit; typedef uint64_t IOReportUnits; // deprecated typo, please switch #define __IOR_MAKEUNIT(quantity, scale) \ (((IOReportUnit)quantity << 56) | (uint64_t)scale) #define IOREPORT_GETUNIT_QUANTITY(unit) \ ((IOReportQuantity)((uint64_t)unit >> 56) & 0xff) #define IOREPORT_GETUNIT_SCALE(unit) \ ((IOReportScaleFactor)unit & 0x00ffffffffffffff) // 8b quantity ID | 32b const val + 8b*2^10 + 8b*2^n | 8b cardinal | 8b unused typedef uint8_t IOReportQuantity; // SI "quantity" is what's measured typedef uint64_t IOReportScaleFactor; // See for a list // of quantities and their symbols. enum { // used by state reports, etc kIOReportQuantityUndefined = 0, kIOReportQuantityTime = 1,// Seconds kIOReportQuantityPower = 2,// Watts kIOReportQuantityEnergy = 3,// Joules kIOReportQuantityCurrent = 4,// Amperes kIOReportQuantityVoltage = 5,// Volts kIOReportQuantityCapacitance = 6,// Farad kIOReportQuantityInductance = 7,// Henry kIOReportQuantityFrequency = 8,// Hertz kIOReportQuantityData = 9,// bits/bytes (see scale) kIOReportQuantityTemperature = 10,// Celsius (not Kelvin :) kIOReportQuantityEventCount = 100, kIOReportQuantityPacketCount = 101, kIOReportQuantityCPUInstrs = 102 }; /* A number of units end up with both IEC (2^n) and SI (10^n) scale factors. * For example, the "MB" of a 1.44 MB floppy or a 1024MHz clock. We * thus support separate 2^n and 10^n factors. The exponent encoding * scheme is modeled loosely on single-precision IEEE 754. */ #define kIOReportScaleConstMask 0x000000007fffffff // constant ("uint31") #define kIOReportScaleOneOver (1LL << 31) // 1/constant #define kIOReportExpBase (-127) // support base^(-n) #define kIOReportExpZeroOffset -(kIOReportExpBase) // max exponent = 128 #define kIOReportScaleSIShift 32 // * 10^n #define kIOReportScaleSIMask 0x000000ff00000000 #define kIOReportScaleIECShift 40 // * 2^n #define kIOReportScaleIECMask 0x0000ff0000000000 #define kIOReportCardinalShift 48 // placeholders #define kIOReportCardinalMask 0x00ff000000000000 /* * Scales are described as a factor times unity: * 1ms = kIOReportScaleMilli * s * * A value expressed in a scaled unit can be scaled to unity via * multiplication by the constant: * 100ms * kIOReportScaleMilli [1e-3] = 0.1s. */ // SI / decimal #define kIOReportScalePico ((-12LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleNano ((-9LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleMicro ((-6LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleMilli ((-3LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleUnity 0 // 10^0 = 2^0 = 1 // unity = 0 is a special case for which we give up exp = -127 #define kIOReportScaleKilo ((3LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleMega ((6LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleGiga ((9LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) #define kIOReportScaleTera ((12LL + kIOReportExpZeroOffset) \ << kIOReportScaleSIShift) // IEC / computer / binary // It's not clear we'll ever use 2^(-n), but 1..2^~120 should suffice. #define kIOReportScaleBits kIOReportScaleUnity #define kIOReportScaleBytes ((3LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) // (bytes have to be added to the exponents up front, can't just OR in) #define kIOReportScaleKibi ((10LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleKiBytes ((13LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleMebi ((20LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleMiBytes ((23LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleGibi ((30LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleGiBytes ((33LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleTebi ((40LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) #define kIOReportScaleTiBytes ((43LL + kIOReportExpZeroOffset) \ << kIOReportScaleIECShift) // can't encode more than 2^125 (keeping bits & bytes inside -126..128) // Also, IOReportScaleValue() is currently limited internally by uint64_t. // Cardinal values, to be filled in appropriately. // Add values in increasing order. #define kIOReportScaleMachHWTicks (1LL << kIOReportCardinalShift) #define kIOReportScaleHWPageSize (2LL << kIOReportCardinalShift) // page scales: 2 pages * 4ikB/page = 8096 bytes #define kIOReportScale4KiB (4 | kIOReportScaleKiBytes) #define kIOReportScale8KiB (8 | kIOReportScaleKiBytes) #define kIOReportScale16KiB (16 | kIOReportScaleKiBytes) // Clock frequency scales (units add seconds). // 1 GHz ticks are 1 ns: 1000 ticks * 1e-6 = 1e-3s // This '1' is a no-op for scaling, but allows a custom label. #define kIOReportScale1GHz (1 | kIOReportScaleNano) // 24MHz ticks are 1/24 of a microsecond: (1/24 * kIOReportScaleMicro [1e-6])s // So for example, 240 24Mticks * 1/24 * 1e-6 = .00001s [1e-5]s #define kIOReportScale24MHz (kIOReportScaleOneOver|24 |kIOReportScaleMicro) // --- END: units mechanism // 2. Unit constants #define kIOReportUnitNone __IOR_MAKEUNIT(kIOReportQuantityUndefined, \ kIOReportScaleUnity) #define kIOReportUnit_s __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScaleUnity) #define kIOReportUnit_ms __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScaleMilli) #define kIOReportUnit_us __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScaleMicro) #define kIOReportUnit_ns __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScaleNano) #define kIOReportUnit_J __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ kIOReportScaleUnity) #define kIOReportUnit_mJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ kIOReportScaleMilli) #define kIOReportUnit_uJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ kIOReportScaleMicro) #define kIOReportUnit_nJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ kIOReportScaleNano) #define kIOReportUnit_pJ __IOR_MAKEUNIT(kIOReportQuantityEnergy, \ kIOReportScalePico) #define kIOReportUnitHWTicks __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScaleMachHWTicks) #define kIOReportUnit24MHzTicks __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScale24MHz) #define kIOReportUnit1GHzTicks __IOR_MAKEUNIT(kIOReportQuantityTime, \ kIOReportScale1GHz) #define kIOReportUnitBits __IOR_MAKEUNIT(kIOReportQuantityData, \ kIOReportScaleBits) #define kIOReportUnitBytes __IOR_MAKEUNIT(kIOReportQuantityData, \ kIOReportScaleBytes) #define kIOReportUnit_KiB __IOR_MAKEUNIT(kIOReportQuantityData, \ kIOReportScaleKiBytes) #define kIOReportUnit_MiB __IOR_MAKEUNIT(kIOReportQuantityData, \ kIOReportScaleMiBytes) #define kIOReportUnit_GiB __IOR_MAKEUNIT(kIOReportQuantityData, \ kIOReportScaleGiBytes) #define kIOReportUnit_TiB __IOR_MAKEUNIT(kIOReportQuantityData, \ kIOReportScaleTiBytes) #define kIOReportUnitEvents __IOR_MAKEUNIT(kIOReportQuantityEventCount, \ kIOReportScaleUnity) #define kIOReportUnitPackets __IOR_MAKEUNIT(kIOReportQuantityPacketCount, \ kIOReportScaleUnity) #define kIOReportUnitInstrs __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ kIOReportScaleUnity) #define kIOReportUnit_KI __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ kIOReportScaleKilo) #define kIOReportUnit_MI __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ kIOReportScaleMega) #define kIOReportUnit_GI __IOR_MAKEUNIT(kIOReportQuantityCPUInstrs, \ kIOReportScaleGiga) // Please file bugs (xnu | IOReporting) for additional units. // --- END: unit constants #ifdef __cplusplus } #endif #endif // _IOREPORT_TYPES_H_