1/*
2 * Copyright (c) 1998-2019 Apple 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 * Copyright (c) 1998 Apple Computer, Inc. All rights reserved.
30 *
31 * HISTORY
32 * 1998-7-13 Godfrey van der Linden(gvdl)
33 * Created.
34 * 1998-10-30 Godfrey van der Linden(gvdl)
35 * Converted to C++
36 */
37
38#ifndef _IOKIT_IOINTERRUPTEVENTSOURCE_H
39#define _IOKIT_IOINTERRUPTEVENTSOURCE_H
40
41#include <libkern/c++/OSPtr.h>
42#include <IOKit/IOEventSource.h>
43
44class IOService;
45
46struct IOInterruptAccountingData;
47
48/*! @class IOInterruptEventSource : public IOEventSource
49 * @abstract Event source for interrupt delivery to work-loop based drivers.
50 * @discussion The IOInterruptEventSource is a generic object that delivers calls interrupt routines in it's client in a guaranteed single-threaded manner. IOInterruptEventSource is part of the IOKit $link IOWorkLoop infrastructure where the semantic that one and only one action method is executing within a work-loops event chain.
51 * <br><br>
52 * When the action method is called in the client member function will receive 2 arguments, (IOEventSource *) sender and (int) count, See $link IOInterruptEventSource::Action. Where sender will be reference to the interrupt that occurred and the count will be computed by the difference between the $link producerCount and $link consumerCount. This number may not be reliable as no attempt is made to adjust for around the world type problems but is provided for general information and statistic gathering.
53 * <br><br>
54 * In general a client will use the factory member function to create and initialise the event source and then add it to their work-loop. It is the work loop's responsiblity to maintain the new event source in it's event chain. See $link IOWorkLoop.
55 * <br><br>
56 * An interrupt event source attaches itself to the given provider's interrupt source at initialisation time. At this time it determines if it is connected to a level or edge triggered interrupt. If the interrupt is an level triggered interrupt the event source automatically disables the interrupt source at primary interrupt time and after it call's the client it automatically reenables the interrupt. This action is fairly expensive but it is 100% safe and defaults sensibly so that the driver writer does not have to implement type dependant interrupt routines. So to repeat, the driver writer does not have to be concerned by the actual underlying interrupt mechanism as the event source hides the complexity.
57 * <br><br>
58 * Saying this if the hardware is a multi-device card, for instance a 4 port NIC, where all of the devices are sharing one level triggered interrupt AND it is possible to determine each port's interrupt state non-destructively then the $link IOFilterInterruptEventSource would be a better choice.
59 * <br><br>
60 * Warning: All IOInterruptEventSources are created in the disabled state. If you want to actually schedule interrupt delivery do not forget to enable the source.
61 */
62class IOInterruptEventSource : public IOEventSource
63{
64 OSDeclareDefaultStructors(IOInterruptEventSource);
65
66public:
67/*! @typedef Action
68 * @discussion 'C' pointer prototype of functions that are called in a single threaded context when an interrupt occurs.
69 * @param owner Pointer to client instance.
70 * @param sender Pointer to generation interrupt event source.
71 * @param count Number of interrupts seen before delivery. */
72 typedef void (*Action)(OSObject *owner, IOInterruptEventSource *sender, int count);
73
74#ifdef __BLOCKS__
75 typedef void (^ActionBlock)(IOInterruptEventSource *sender, int count);
76#endif /* __BLOCKS__ */
77
78/*! @defined IOInterruptEventAction
79 * @discussion Backward compatibilty define for the old non-class scoped type definition. See $link IOInterruptEventSource::Action */
80#define IOInterruptEventAction IOInterruptEventSource::Action
81
82protected:
83/*! @var provider IOService that provides interrupts for delivery. */
84 IOService *provider;
85
86/*! @var intIndex */
87 int intIndex;
88
89/*! @var producerCount
90 * Current count of produced interrupts that have been received. */
91 volatile unsigned int producerCount;
92
93/*! @var consumerCount
94 * Current count of produced interrupts that the owner has been informed of. */
95 unsigned int consumerCount;
96
97/*! @var autoDisable Do we need to automatically disable the interrupt source when we take an interrupt, i.e. we are level triggered. */
98 bool autoDisable;
99
100/*! @var explicitDisable Has the user expicitly disabled this event source, if so then do not overide their request when returning from the callout */
101 bool explicitDisable;
102
103/*! @struct ExpansionData
104 * @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
105 */
106 struct ExpansionData {
107 IOInterruptAccountingData * statistics;
108 };
109
110/*! @var reserved
111 * Reserved for future use. (Internal use only) */
112 APPLE_KEXT_WSHADOW_PUSH;
113 ExpansionData *reserved;
114 APPLE_KEXT_WSHADOW_POP;
115
116/*! @function free
117 * @abstract Sub-class implementation of free method, disconnects from the interrupt source. */
118 virtual void free() APPLE_KEXT_OVERRIDE;
119
120/*! @function checkForWork
121 * @abstract Pure Virtual member function used by IOWorkLoop for issueing a client calls.
122 * @discussion This function called when the work-loop is ready to check for any work to do and then to call out the owner/action.
123 * @result Return true if this function needs to be called again before all its outstanding events have been processed. */
124 virtual bool checkForWork() APPLE_KEXT_OVERRIDE;
125
126/*! @function setWorkLoop
127 * @abstract Sub-class implementation of setWorkLoop method. */
128 virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE;
129
130public:
131
132/*! @function interruptEventSource
133 * @abstract Factory function for IOInterruptEventSources creation and initialisation.
134 * @param owner Owning client of the new event source.
135 * @param action 'C' Function to call when something happens.
136 * @param provider IOService that represents the interrupt source. Defaults to 0. When no provider is defined the event source assumes that the client will in some manner call the interruptOccured method explicitly. This will start the ball rolling for safe delivery of asynchronous event's into the driver.
137 * @param intIndex The index of the interrupt within the provider's interrupt sources. Defaults to 0, i.e. the first interrupt in the provider.
138 * @result A new interrupt event source if successfully created and initialised, 0 otherwise. */
139 static OSPtr<IOInterruptEventSource>
140 interruptEventSource(OSObject *owner,
141 Action action,
142 IOService *provider = NULL,
143 int intIndex = 0);
144
145
146#ifdef __BLOCKS__
147/*! @function interruptEventSource
148 * @abstract Factory function for IOInterruptEventSources creation and initialisation.
149 * @param owner Owning client of the new event source.
150 * @param provider IOService that represents the interrupt source. When no provider is defined the event source assumes that the client will in some manner call the interruptOccured method explicitly. This will start the ball rolling for safe delivery of asynchronous event's into the driver.
151 * @param intIndex The index of the interrupt within the provider's interrupt sources.
152 * @param action Block for the callout routine of this event source..
153 * @result A new interrupt event source if successfully created and initialised, 0 otherwise. */
154 static OSPtr<IOInterruptEventSource>
155 interruptEventSource(OSObject *owner,
156 IOService *provider,
157 int intIndex,
158 ActionBlock action);
159#endif /* __BLOCKS__ */
160
161#if XNU_KERNEL_PRIVATE
162 static void actionToBlock(OSObject *owner, IOInterruptEventSource *sender, int count);
163#endif /* XNU_KERNEL_PRIVATE */
164
165/*! @function init
166 * @abstract Primary initialiser for the IOInterruptEventSource class.
167 * @param owner Owning client of the new event source.
168 * @param action 'C' Function to call when something happens.
169 * @param provider IOService that represents the interrupt source. Defaults to 0. When no provider is defined the event source assumes that the client will in some manner call the interruptOccured method explicitly. This will start the ball rolling for safe delivery of asynchronous event's into the driver.
170 * @param intIndex The index of the interrupt within the provider's interrupt sources. Defaults to 0, i.e. the first interrupt in the provider.
171 * @result true if the inherited classes and this instance initialise
172 * successfully. */
173 virtual bool init(OSObject *owner,
174 Action action,
175 IOService *provider = NULL,
176 int intIndex = 0);
177
178/*! @function enable
179 * @abstract Enable event source.
180 * @discussion A subclass implementation is expected to respect the enabled
181 * state when checkForWork is called. Calling this function will cause the
182 * work-loop to be signalled so that a checkForWork is performed. */
183 virtual void enable() APPLE_KEXT_OVERRIDE;
184
185/*! @function disable
186 * @abstract Disable event source.
187 * @discussion A subclass implementation is expected to respect the enabled
188 * state when checkForWork is called. */
189 virtual void disable() APPLE_KEXT_OVERRIDE;
190
191/*! @function getProvider
192 * @abstract Get'ter for $link provider variable.
193 * @result value of provider. */
194 virtual const IOService *getProvider() const;
195
196/*! @function getIntIndex
197 * @abstract Get'ter for $link intIndex interrupt index variable.
198 * @result value of intIndex. */
199 virtual int getIntIndex() const;
200
201/*! @function getAutoDisable
202 * @abstract Get'ter for $link autoDisable variable.
203 * @result value of autoDisable. */
204 virtual bool getAutoDisable() const;
205
206/*! @function interruptOccurred
207 * @abstract Functions that get called by the interrupt controller. See $link IOService::registerInterrupt
208 * @param nub Where did the interrupt originate from
209 * @param ind What is this interrupts index within 'nub'. */
210 virtual void interruptOccurred(void *, IOService *nub, int ind);
211
212/*! @function normalInterruptOccurred
213 * @abstract Functions that get called by the interrupt controller.See $link IOService::registerInterrupt
214 * @param nub Where did the interrupt originate from
215 * @param ind What is this interrupts index within 'nub'. */
216 virtual void normalInterruptOccurred(void *, IOService *nub, int ind);
217
218/*! @function disableInterruptOccurred
219 * @abstract Functions that get called by the interrupt controller.See $link IOService::registerInterrupt
220 * @param nub Where did the interrupt originate from
221 * @param ind What is this interrupts index within 'nub'. */
222 virtual void disableInterruptOccurred(void *, IOService *nub, int ind);
223
224/*! @function warmCPU
225 * @abstract Tries to reduce latency for an interrupt which will be received near a specified time.
226 * @discussion Warms up a CPU in advance of an interrupt so that the interrupt may be serviced with predictable latency.
227 * The warm-up is not periodic; callers should call warmCPU once in advance of each interrupt. It is recommended that
228 * requests be issues in serial (i.e. each after the target for the previous call has elapsed), as there is a systemwide
229 * cap on the number of outstanding requests. This routine may be disruptive to the system if used with very small intervals
230 * between requests; it should be used only in cases where interrupt latency is absolutely critical, and tens or hundreds of
231 * milliseconds between targets is the expected time scale. NOTE: it is not safe to call this method with interrupts disabled.
232 * @param abstime Time at which interrupt is expected. */
233 IOReturn warmCPU(uint64_t abstime);
234
235/*! @function enablePrimaryInterruptTimestamp
236 * @abstract Enables collection of mach_absolute_time at primary interrupt.
237 * @discussion Enables collection of mach_absolute_time at primary interrupt.
238 * @param enable True to enable timestamp. */
239
240 void enablePrimaryInterruptTimestamp(bool enable);
241
242/*! @function getPrimaryInterruptTimestamp
243 * @abstract Returns mach_absolute_time timestamp of primary interrupt.
244 * @discussion Returns mach_absolute_time timestamp of primary interrupt.
245 * @result Value of the timestamp. Zero if never interrupted, or -1ULL if timestamp collection has not been enabled. */
246
247 uint64_t getPrimaryInterruptTimestamp();
248
249private:
250 IOReturn registerInterruptHandler(IOService *inProvider, int inIntIndex);
251 void unregisterInterruptHandler(IOService *inProvider, int inIntIndex);
252
253private:
254 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 0);
255 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 1);
256 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 2);
257 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 3);
258 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 4);
259 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 5);
260 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 6);
261 OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 7);
262};
263
264#endif /* !_IOKIT_IOINTERRUPTEVENTSOURCE_H */
265