iokit/IOKit/IOReportTypes.h

   1 /*
   2  * @APPLE_LICENSE_HEADER_START@
   3  *
   4  * Copyright (c) 2012 Apple Computer, Inc.  All Rights Reserved.
   5  *
   6  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. The rights granted to you under the License
  12  * may not be used to create, or enable the creation or redistribution of,
  13  * unlawful or unlicensed copies of an Apple operating system, or to
  14  * circumvent, violate, or enable the circumvention or violation of, any
  15  * terms of an Apple operating system software license agreement.
  16  *
  17  * Please obtain a copy of the License at
  18  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  29  */
  30
  31 #ifndef _IOREPORT_TYPES_H_
  32 #define _IOREPORT_TYPES_H_
  33
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  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 kIOReportInvalidValue UINT64_MAX
  50 #define kIOReportInvalidIntValue (int64_t)kIOReportInvalidValue
  51
  52 // IOReportChannelType.categories
  53 typedef uint16_t IOReportCategories;
  54 #define kIOReportCategoryPower           (1 << 1)       // and energy
  55 #define kIOReportCategoryTraffic         (1 << 2)
  56 #define kIOReportCategoryPerformance     (1 << 3)
  57 #define kIOReportCategoryPeripheral      (1 << 4)
  58 // future categories TBD
  59 #define kIOReportCategoryDebug           (1 << 15)
  60 #define kIOReportInvalidCategory         UINT16_MAX
  61
  62
  63 // IOReportChannelType.report_format
  64 typedef uint8_t IOReportFormat;
  65 enum {
  66    kIOReportInvalidFormat = 0,
  67    kIOReportFormatSimple = 1,
  68    kIOReportFormatState = 2,
  69    kIOReportFormatHistogram = 3
  70 };
  71
  72 // simple report values
  73 typedef struct {
  74     int64_t    simple_value;
  75     uint64_t    reserved1;
  76     uint64_t    reserved2;
  77     uint64_t    reserved3;
  78 } __attribute((packed)) IOSimpleReportValues;
  79
  80 // state report values
  81 typedef struct {
  82     uint64_t    state_id;           // 0..N-1 or 8-char code (see MAKEID())
  83     uint64_t    intransitions;      // number of transitions into this state
  84     uint64_t    upticks;            // ticks spent in state (local timebase)
  85     uint64_t    last_intransition;  // ticks at last in-transition
  86 } __attribute((packed)) IOStateReportValues;
  87
  88 // histograme report values
  89 typedef struct {
  90     uint64_t    bucket_hits;
  91     int64_t     bucket_min;
  92     int64_t     bucket_max;
  93     int64_t     bucket_sum;
  94 } __attribute((packed)) IOHistogramReportValues;
  95
  96 // configuration actions generally change future behavior
  97 typedef uint32_t IOReportConfigureAction;
  98 enum {
  99     // basics (in common operational order)
 100     kIOReportEnable             = 0x01,
 101     kIOReportGetDimensions      = 0x02,
 102     kIOReportDisable            = 0x00,
 103
 104     // Enable/disable modifiers
 105     kIOReportNotifyHubOnChange  = 0x10,     // triggered polling
 106
 107     kIOReportTraceOnChange      = 0x20      // kdebug.h tracing
 108 };
 109
 110 // update actions should not have observable side effects
 111 typedef uint32_t IOReportUpdateAction;
 112 enum {
 113     kIOReportCopyChannelData    = 1,
 114     kIOReportTraceChannelData   = 2
 115 };
 116
 117 typedef struct {
 118     uint8_t     report_format;      // Histogram, StateResidency, etc.
 119     uint8_t     reserved;           // must be zero
 120     uint16_t    categories;         // power, traffic, etc (omnibus obs.)
 121     uint16_t    nelements;          // internal size of channel
 122
 123     // only meaningful in the data pipeline
 124     int16_t     element_idx;        // 0..nelements-1
 125                                     // -1..-(nelements) = invalid (13127884)
 126 } __attribute((packed)) IOReportChannelType;
 127
 128 /*!
 129     @define     IOREPORT_MAKECHID
 130     @abstract   convert up to 8 printable characters into a 64-bit channel ID
 131     @param  <char0..char7> - printable chars to be packed into a channel ID
 132     @result     a 64-bit channel ID with an implicit ASCII name
 133     @discussion A simple example:
 134                 IOREPORT_MAKECHID('H', 'i', ' ', 'w', 'o', 'r', 'l', 'd');
 135                 will evaluate to 0x686920776f726c64.  Any NUL bytes are
 136                 ignored (by libIOReport) for naming purposes, but will
 137                 appear in the channel ID.  Using a non-NUL non-printable
 138                 character will disable the implicit name.  Putting NUL
 139                 bytes first eliminates trailing zeros when the channel
 140                 ID is printed as hex.  For example:
 141                 IORERPORT_MAKECHID('\0','\0','n','x','f','e','r','s');
 142                 To see the text, use xxd -r -p # not -rp; see 12976241
 143 */
 144 #define __IOR_lshiftchr(c, chshift)     ((uint64_t)(c) << (8*(chshift)))
 145 #define IOREPORT_MAKEID(A, B, C, D, E, F, G, H) \
 146     (__IOR_lshiftchr(A, 7) | __IOR_lshiftchr(B, 6) | __IOR_lshiftchr(C, 5) \
 147     | __IOR_lshiftchr(D, 4) | __IOR_lshiftchr(E, 3) | __IOR_lshiftchr(F, 2) \
 148     | __IOR_lshiftchr(G, 1) | __IOR_lshiftchr(H, 0))
 149
 150 typedef struct {
 151     uint64_t                channel_id;
 152     IOReportChannelType     channel_type;
 153 } IOReportChannel;
 154
 155 typedef struct {
 156     uint32_t                nchannels;
 157     IOReportChannel         channels[];
 158 } IOReportChannelList;
 159
 160 typedef struct {
 161     uint64_t                provider_id;
 162     IOReportChannel         channel;
 163 } IOReportInterest;
 164
 165 typedef struct {
 166     uint32_t                ninterests;
 167     IOReportInterest        interests[];
 168 } IOReportInterestList;
 169
 170 typedef struct {
 171     uint64_t                v[4];
 172 } __attribute((packed)) IOReportElementValues;
 173
 174 typedef struct {
 175     uint64_t                provider_id;
 176     uint64_t                channel_id;
 177     IOReportChannelType     channel_type;
 178     uint64_t                timestamp;   // mach_absolute_time()
 179     IOReportElementValues   values;
 180 } __attribute((packed)) IOReportElement;
 181
 182 #ifdef __cplusplus
 183 }
 184 #endif
 185
 186 #endif // _IOREPORT_TYPES_H_