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
37extern "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
53typedef 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
64typedef uint8_t IOReportFormat;
65enum {
66   kIOReportInvalidFormat = 0,
67   kIOReportFormatSimple = 1,
68   kIOReportFormatState = 2,
69   kIOReportFormatHistogram = 3
70};
71
72// simple report values
73typedef 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
81typedef 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
89typedef 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
97typedef uint32_t IOReportConfigureAction;
98enum {
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
111typedef uint32_t IOReportUpdateAction;
112enum {
113    kIOReportCopyChannelData    = 1,
114    kIOReportTraceChannelData   = 2
115};
116
117typedef 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
150typedef struct {
151    uint64_t                channel_id;
152    IOReportChannelType     channel_type;
153} IOReportChannel;
154
155typedef struct {
156    uint32_t                nchannels;
157    IOReportChannel         channels[];
158} IOReportChannelList;
159
160typedef struct {
161    uint64_t                provider_id;
162    IOReportChannel         channel;
163} IOReportInterest;
164
165typedef struct {
166    uint32_t                ninterests;
167    IOReportInterest        interests[];
168} IOReportInterestList;
169
170typedef struct {
171    uint64_t                v[4];
172} __attribute((packed)) IOReportElementValues;
173
174typedef 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_
187