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 35extern "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*/ 63typedef 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 78typedef uint8_t IOReportFormat; 79enum { 80 kIOReportInvalidFormat = 0, 81 kIOReportFormatSimple = 1, 82 kIOReportFormatState = 2, 83 kIOReportFormatHistogram = 3, 84 kIOReportFormatSimpleArray = 4 85}; 86 87// simple report values 88typedef 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 96typedef struct { 97 int64_t simple_values[IOR_VALUES_PER_ELEMENT]; 98} __attribute((packed)) IOSimpleArrayReportValues; 99 100// state report values 101typedef 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 109typedef 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 119typedef uint32_t IOReportConfigureAction; 120enum { 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 133typedef uint32_t IOReportUpdateAction; 134enum { 135 kIOReportCopyChannelData = 1, 136 kIOReportTraceChannelData = 2 137}; 138 139typedef 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 172typedef struct { 173 uint64_t channel_id; 174 IOReportChannelType channel_type; 175} IOReportChannel; 176 177typedef struct { 178 uint32_t nchannels; 179 IOReportChannel channels[]; 180} IOReportChannelList; 181 182typedef struct { 183 uint64_t provider_id; 184 IOReportChannel channel; 185} IOReportInterest; 186 187typedef struct { 188 uint32_t ninterests; 189 IOReportInterest interests[]; 190} IOReportInterestList; 191 192typedef struct { 193 uint64_t v[IOR_VALUES_PER_ELEMENT]; 194} __attribute((packed)) IOReportElementValues; 195 196typedef 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_ 209