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