/*
* 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 <stdint.h>
#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 <char0..char7> - 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 <http://en.wikipedia.org/wiki/SI_base_unit> 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_