IOReportTypes.h

/*
 * 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_