iokit/IOKit/IOReportTypes.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 #ifndef _IOREPORT_TYPES_H_
  30 #define _IOREPORT_TYPES_H_
  31
  32 #include <stdint.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #define IOR_VALUES_PER_ELEMENT  4
  39
  40 /*! @const      kIOReportInvalidValue
  41     @const      kIOReportInvalidIntValue
  42     @abstract   cardinal value used to indicate data errors
  43
  44     @discussion
  45         kIOReportInvalidValue and kIOReportInvalidIntValue have the
  46         same bit pattern so that clients checking for one or the other
  47         don't have to worry about getting the signedness right.
  48 */
  49 #define kIOReportInvalidIntValue INT64_MIN
  50 #define kIOReportInvalidValue (uint64_t)kIOReportInvalidIntValue
  51
  52 /*! @typedef    IOReportCategories
  53     @abstract   encapsulate important, multi-purpose "tags" for channels
  54
  55     @discussion
  56         IOReportCategories is the type for the .categories field of
  57         IOReportChanelType.  These categories are inteded to empower a
  58         limited number of clients to retrieve a broad range of channels
  59         without knowing much about them.  They can be OR'd together as
  60         needed.  Groups and subgroups are a more extensible mechanism
  61         for aggregating channels produced by different drivers.
  62 */
  63 typedef uint16_t IOReportCategories;
  64 #define kIOReportCategoryPower           (1 << 1)       // and energy
  65 #define kIOReportCategoryTraffic         (1 << 2)       // I/O at any level
  66 #define kIOReportCategoryPerformance     (1 << 3)       // e.g. cycles/byte
  67 #define kIOReportCategoryPeripheral      (1 << 4)       // not built-in
  68
  69 #define kIOReportCategoryField           (1 << 8)       // consider logging
  70
  71 // future categories TBD
  72 #define kIOReportCategoryInterrupt       (1 << 14)      // TBR: 15850269
  73 #define kIOReportCategoryDebug           (1 << 15)
  74 #define kIOReportInvalidCategory         UINT16_MAX
  75
  76
  77 // IOReportChannelType.report_format
  78 typedef uint8_t IOReportFormat;
  79 enum {
  80    kIOReportInvalidFormat = 0,
  81    kIOReportFormatSimple = 1,
  82    kIOReportFormatState = 2,
  83    kIOReportFormatHistogram = 3,
  84    kIOReportFormatSimpleArray = 4
  85 };
  86
  87 // simple report values
  88 typedef struct {
  89     int64_t    simple_value;
  90     uint64_t    reserved1;
  91     uint64_t    reserved2;
  92     uint64_t    reserved3;
  93 } __attribute((packed)) IOSimpleReportValues;
  94
  95 // simple value array
  96 typedef struct {
  97     int64_t    simple_values[IOR_VALUES_PER_ELEMENT];
  98 } __attribute((packed)) IOSimpleArrayReportValues;
  99
 100 // state report values
 101 typedef struct {
 102     uint64_t    state_id;           // 0..N-1 or 8-char code (see MAKEID())
 103     uint64_t    intransitions;      // number of transitions into this state
 104     uint64_t    upticks;            // ticks spent in state (local timebase)
 105     uint64_t    last_intransition;  // ticks at last in-transition
 106 } __attribute((packed)) IOStateReportValues;
 107
 108 // histogram report values
 109 typedef struct {
 110     uint64_t    bucket_hits;
 111     int64_t     bucket_min;
 112     int64_t     bucket_max;
 113     int64_t     bucket_sum;
 114 } __attribute((packed)) IOHistogramReportValues;
 115
 116
 117
 118 // configuration actions generally change future behavior
 119 typedef uint32_t IOReportConfigureAction;
 120 enum {
 121     // basics (in common operational order)
 122     kIOReportEnable             = 0x01,
 123     kIOReportGetDimensions      = 0x02,
 124     kIOReportDisable            = 0x00,
 125
 126     // Enable/disable modifiers
 127     kIOReportNotifyHubOnChange  = 0x10,     // triggered polling
 128
 129     kIOReportTraceOnChange      = 0x20      // kdebug.h tracing
 130 };
 131
 132 // update actions should not have observable side effects
 133 typedef uint32_t IOReportUpdateAction;
 134 enum {
 135     kIOReportCopyChannelData    = 1,
 136     kIOReportTraceChannelData   = 2
 137 };
 138
 139 typedef struct {
 140     uint8_t     report_format;      // Histogram, StateResidency, etc.
 141     uint8_t     reserved;           // must be zero
 142     uint16_t    categories;         // power, traffic, etc (omnibus obs.)
 143     uint16_t    nelements;          // internal size of channel
 144
 145     // only meaningful in the data pipeline
 146     int16_t     element_idx;        // 0..nelements-1
 147                                     // -1..-(nelements) = invalid (13127884)
 148 } __attribute((packed)) IOReportChannelType;
 149
 150 /*!
 151     @define     IOREPORT_MAKECHID
 152     @abstract   convert up to 8 printable characters into a 64-bit channel ID
 153     @param  <char0..char7> - printable chars to be packed into a channel ID
 154     @result     a 64-bit channel ID with an implicit ASCII name
 155     @discussion A simple example:
 156                 IOREPORT_MAKECHID('H', 'i', ' ', 'w', 'o', 'r', 'l', 'd');
 157                 will evaluate to 0x686920776f726c64.  Any NUL bytes are
 158                 ignored (by libIOReport) for naming purposes, but will
 159                 appear in the channel ID.  Using a non-NUL non-printable
 160                 character will disable the implicit name.  Putting NUL
 161                 bytes first eliminates trailing zeros when the channel
 162                 ID is printed as hex.  For example:
 163                 IORERPORT_MAKECHID('\0','\0','n','x','f','e','r','s');
 164                 To see the text, use xxd -r -p # not -rp; see 12976241
 165 */
 166 #define __IOR_lshiftchr(c, chshift)     ((uint64_t)(c) << (8*(chshift)))
 167 #define IOREPORT_MAKEID(A, B, C, D, E, F, G, H) \
 168     (__IOR_lshiftchr(A, 7) | __IOR_lshiftchr(B, 6) | __IOR_lshiftchr(C, 5) \
 169     | __IOR_lshiftchr(D, 4) | __IOR_lshiftchr(E, 3) | __IOR_lshiftchr(F, 2) \
 170     | __IOR_lshiftchr(G, 1) | __IOR_lshiftchr(H, 0))
 171
 172 typedef struct {
 173     uint64_t                channel_id;
 174     IOReportChannelType     channel_type;
 175 } IOReportChannel;
 176
 177 typedef struct {
 178     uint32_t                nchannels;
 179     IOReportChannel         channels[];
 180 } IOReportChannelList;
 181
 182 typedef struct {
 183     uint64_t                provider_id;
 184     IOReportChannel         channel;
 185 } IOReportInterest;
 186
 187 typedef struct {
 188     uint32_t                ninterests;
 189     IOReportInterest        interests[];
 190 } IOReportInterestList;
 191
 192 typedef struct {
 193     uint64_t                v[IOR_VALUES_PER_ELEMENT];
 194 } __attribute((packed)) IOReportElementValues;
 195
 196 typedef struct {
 197     uint64_t                provider_id;
 198     uint64_t                channel_id;
 199     IOReportChannelType     channel_type;
 200     uint64_t                timestamp;   // mach_absolute_time()
 201     IOReportElementValues   values;
 202 } __attribute((packed)) IOReportElement;
 203
 204 #ifdef __cplusplus
 205 }
 206 #endif
 207
 208 #endif // _IOREPORT_TYPES_H_