1 | /* |
2 | * Copyright (c) 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 __IOKIT_IOINTERRUPTACCOUNTING_H |
30 | #define __IOKIT_IOINTERRUPTACCOUNTING_H |
31 | |
32 | #include <IOKit/IOReportTypes.h> |
33 | |
34 | /* |
35 | * This header contains definitions that will be needed by userspace clients of the interrupt accounting |
36 | * mechanisms. |
37 | */ |
38 | |
39 | #define IA_INDEX_MAX (255) |
40 | #define IA_INDEX_MASK (0xFFULL) |
41 | #define IA_STATISTIC_INDEX_SHIFT (0ULL) |
42 | #define IA_INTERRUPT_INDEX_SHIFT (16ULL) |
43 | |
44 | /* |
45 | * For the moment, the indices aren't preprocessor visible, so any changes to this code will need to be |
46 | * careful to ensure that the defined number of statistics matches (or is greater than) the actual number |
47 | * of statistics, to avoid channel ID collisions... because that would be bad. |
48 | */ |
49 | #define IA_NUM_INTERRUPT_ACCOUNTING_STATISTICS (10) |
50 | |
51 | /* |
52 | * Channel ID related definitions. These serve to denote the namespace of interrupt accounting in the |
53 | * context of IOReporter-based clients. Interrupt accounting distinguishes between interrupts based on |
54 | * the nub the interrupt was registered relative to, and the nub relative interrupt index (i.e, the |
55 | * namespace for interrupt accounting is {nub ID, interrupt index}). IOReporting already knows about |
56 | * nubs (in the context of IOService), however it has no built in knowledge of interrupt accounting. |
57 | * As a result of this, it is the responsibility of the IOReporting client to request any desired |
58 | * statistics on a per-index basis (i.e, if you want to get the first level interrupt count for all |
59 | * interrupts, you must express an interest in the first level interrupt count statistic for index 0, 1, |
60 | * 2, and so on, to a reasonable maximum). |
61 | */ |
62 | |
63 | /* |
64 | * These delimit the channel ID namespace for interrupt accounting. |
65 | */ |
66 | #define IA_BASE_CHANNEL_ID IOREPORT_MAKEID('I', 'n', 't', 'r', 0, 0, 0, 0) /* First valid channel ID */ |
67 | #define IA_MAX_CHANNEL_ID IOREPORT_MAKEID('I', 'n', 't', 'r', 0xFF, 0xFF, 0xFF, 0xFF) /* Last valid channel ID */ |
68 | |
69 | /* |
70 | * Given a nub-relative interrupt index (an index into the interrupt specifiers), and the index of a |
71 | * interrupt accounting statistic, returns the channel id for that statistic. |
72 | */ |
73 | #define IA_GET_CHANNEL_ID(interruptIndex, statisticIndex) \ |
74 | ((IA_BASE_CHANNEL_ID) + \ |
75 | ((interruptIndex % IA_INDEX_MASK) << IA_INTERRUPT_INDEX_SHIFT) + \ |
76 | ((statisticIndex % IA_INDEX_MASK) << IA_STATISTIC_INDEX_SHIFT)) |
77 | |
78 | /* |
79 | * Extracts the interrupt index, given a channel ID. |
80 | */ |
81 | #define IA_GET_INTERRUPT_INDEX(channelID) \ |
82 | (((channelID - IA_BASE_CHANNEL_ID) >> IA_INTERRUPT_INDEX_SHIFT) % IA_INDEX_MASK) |
83 | |
84 | /* |
85 | * Extracts the statistic index, given a channel ID. |
86 | */ |
87 | #define IA_GET_STATISTIC_INDEX(channelID) \ |
88 | (((channelID - IA_BASE_CHANNEL_ID) >> IA_STATISTIC_INDEX_SHIFT) % IA_INDEX_MASK) |
89 | |
90 | /* |
91 | * This enum defines the basic statistics we gather for each interrupt. Currently, the information |
92 | * we gather falls into roughly three buckets: interrupt related (counts, times), scheduler related |
93 | * (thread wakeups), and power related (package/cpu state changes). |
94 | * |
95 | * First Level Count: This represents the number of times that this interrupt has fired (more |
96 | * specifically, the number of times we have run the handler we expect to run in interrupt context). |
97 | * |
98 | * Second Level Count: This represents the number of times we have run any second level handler for |
99 | * this interrupt (more specifically, the handler we expect to be run in the regular kernel context). |
100 | * |
101 | * First Level Time: This represents the aggregate time spent running the first level handler. For |
102 | * some interrupts, this value will be 0, as this is not meant to track time spent running generic |
103 | * IOKit code for the interrupt (i.e, IOInterruptEventSource code), but instead any custom code run |
104 | * at the interrupt context (i.e, the filter installed for an IOFilterInterruptEventSource). |
105 | * |
106 | * Second Level CPU Time: This represents the aggregate time spent actually running the second level |
107 | * handler on the CPU. As the second level handler may block or be preempted, it is meaningful to |
108 | * distinguish this from the system time spent handling the interrupt. As was the case for the |
109 | * first level handler, this does not attempt to track the time spent running generic IOKit code |
110 | * (i.e, IOInterruptEventSource code or IOWorkLoop code), but instead attempts to track the time |
111 | * spent running the handler that was installed. |
112 | * |
113 | * Second Level System Time: This represents the aggregate time spent in the second level handler; |
114 | * this will include time where the handler was blocked or had been preempted. This should equate |
115 | * to the wall time spent handling an interrupt (as long as we don't allow the system to go to |
116 | * sleep while a second level handler is running). |
117 | * |
118 | * No Thread Wakeups: The number of times that the interrupt did not attempt to wake up a thread |
119 | * (typically the work loop for the interrupt source is woken up). |
120 | * |
121 | * Total Thread Wakeups: The aggregate number of threads (non-unique) woken up by the interrupt. |
122 | * If no threads were actually woken up for an interrupt (i.e, the work loop thread was already |
123 | * runnable), this value will not change. |
124 | * |
125 | * Package Wakeups: The number of times that this interrupt woke up the package (as defined by the |
126 | * scheduler). |
127 | * |
128 | * CPU Wakeups: The number of times that this interrupt woke up a CPU (forcing it to go through the |
129 | * reset path). |
130 | * |
131 | * Idle Exits: The number of times that this interrupt forced a CPU out of the idle loop (the CPU |
132 | * had to exit an idle state to handle the interrupt, but it did not need to go through the reset |
133 | * path). |
134 | */ |
135 | enum { |
136 | kInterruptAccountingFirstLevelCountIndex = 0, /* Number of times we invoked the top level handler */ |
137 | kInterruptAccountingSecondLevelCountIndex, /* Number of times we invoked the workloop action */ |
138 | kInterruptAccountingFirstLevelTimeIndex, /* Time spent in the top level handler, if one was installed */ |
139 | kInterruptAccountingSecondLevelCPUTimeIndex, /* CPU time spent in the workloop action */ |
140 | kInterruptAccountingSecondLevelSystemTimeIndex, /* System time spent in the workloop action */ |
141 | kInterruptAccountingNoThreadWakeupsIndex, /* Number of first level (filter) invocations that did not wake up a thread */ |
142 | kInterruptAccountingTotalThreadWakeupsIndex, /* Number of actual thread wakeups caused by this interrupt */ |
143 | kInterruptAccountingPackageWakeupsIndex, /* Number of times this interrupt woke up the package */ |
144 | kInterruptAccountingCPUWakeupsIndex, /* Number of times this interrupt woke up a CPU */ |
145 | kInterruptAccountingIdleExitsIndex, /* Number of times this interrupt forced a CPU out of the idle loop */ |
146 | kInterruptAccountingInvalidStatisticIndex /* Sentinel value for checking for a nonsensical index */ |
147 | }; |
148 | |
149 | /* |
150 | * IOReporting group name; exposed publicly for the purpose of getting channels by group |
151 | * name; other strings (subgroup names, statistic names) are not exposed, as we may want |
152 | * to change them in the future. |
153 | */ |
154 | #define kInterruptAccountingGroupName "Interrupt Statistics (by index)" |
155 | |
156 | #endif /* __IOKIT_IOINTERRUPTACCOUNTING_PRIVATE_H */ |
157 | |