1/*
2 * Copyright (c) 2019-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#ifndef _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H
30#define _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H
31
32#include <DriverKit/IODispatchQueue.iig>
33#include <DriverKit/IOService.iig>
34
35struct IOInterruptDispatchSourcePayload {
36	uint64_t time;
37	uint64_t count;
38};
39
40enum {
41	kIOInterruptDispatchSourceTypeEdge  = 0x00000000,
42	kIOInterruptDispatchSourceTypeLevel = 0x00000001
43};
44
45enum {
46	kIOInterruptSourceIndexMask      = 0x0000FFFF,
47	kIOInterruptSourceAbsoluteTime   = 0x00000000,
48	kIOInterruptSourceContinuousTime = 0x00010000
49};
50
51/*!
52 * @class IOInterruptDispatchSource
53 *
54 * @abstract
55 * IOInterruptDispatchSource delivers interrupts to a handler block on a dispatch queue.
56 *
57 * @discussion
58 * A driver can run code in response to an interrupt from a device, specified as an IOService
59 * and index. The code runs at normal thread level, but is notified with the mach_absolute_time
60 * the primary interrupt fired. For IOPCIDevices, only MSI interrupt sources are supported.
61 */
62
63class NATIVE KERNEL IOInterruptDispatchSource : public IODispatchSource
64{
65public:
66
67    /*!
68     * @brief       Create an IOInterruptDispatchSource for an interrupt by index from an IOService provider.
69     * @param       provider The IOService object representing the HW device producing the interrupt.
70     * @param       index Index for the interrupt, optionally or'ed with one of the following constants:
71                    kIOInterruptSourceContinuousTime time values sent to the InterruptOccurred() method will be in mach_continuous_time() units.
72     * @param       queue Target queue to run the handler block.
73     * @param       source Created source with +1 retain count to be released by the caller.
74     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
75     */
76	static kern_return_t
77	Create(IOService * provider,
78	    uint32_t index,
79	    IODispatchQueue * queue,
80	    IOInterruptDispatchSource ** source) LOCAL;
81
82    /*!
83     * @brief       Returns the type of interrupt used for a device supplying hardware interrupts, by index from an IOService provider.
84     * @param       provider The IOService object representing the HW device producing the interrupt.
85     * @param       index Index for the interrupt.
86     * @param 		interruptType The interrupt type for the interrupt source will be stored here.
87     *              kIOInterruptTypeEdge will be returned for edge-trigggered sources.
88     *              kIOInterruptTypeLevel will be returned for level-trigggered sources.
89     *              Other flags may be returned depending on the provider, for example PCI flags for messaged interrupts.
90     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
91     */
92
93	static kern_return_t
94	GetInterruptType(IOService * provider,
95	    uint32_t index,
96	    uint64_t * interruptType);
97
98	virtual bool
99	init() override;
100
101	virtual void
102	free() override;
103
104    /*!
105     * @brief       Set the handler block to run when the interupt fires.
106     * @param       action OSAction instance specifying the callback method. The OSAction object will be retained
107     *              until SetHandler is called again or the event source is cancelled.
108     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
109     */
110	virtual kern_return_t
111	    SetHandler(
112		OSAction * action TYPE(InterruptOccurred)) LOCAL;
113
114    /*!
115     * @brief       Control the enable state of the interrupt source.
116     * @param       enable Pass true to enable the source or false to disable.
117     * @param       handler Optional block to be executed after the interrupt has been disabled and any pending
118     *              interrupt handlers completed.
119     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
120     */
121	virtual kern_return_t
122	SetEnableWithCompletion(
123		bool enable,
124		IODispatchSourceCancelHandler handler) override LOCAL;
125
126    /*!
127     * @brief       Cancel all callbacks from the event source.
128     * @discussion  After cancellation, the source can only be freed. It cannot be reactivated.
129     * @param       handler Handler block to be invoked after any callbacks have completed.
130     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
131     */
132	virtual kern_return_t
133	Cancel(IODispatchSourceCancelHandler handler) override LOCAL;
134
135    /*!
136     * @brief       Get the count and time of the last interrupt received by the kernel
137                    primary interrupt handler.
138     * @param       count Interrupt count.
139     * @param       time Interrupt time.
140     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
141     */
142	virtual kern_return_t
143	GetLastInterrupt(
144		uint64_t   * count,
145		uint64_t   * time);
146
147private:
148	virtual kern_return_t
149	CheckForWork(bool synchronous) override LOCAL;
150
151	virtual void
152	InterruptOccurred(
153		OSAction * action TARGET,
154		uint64_t   count,
155		uint64_t   time) REPLY LOCAL;
156};
157
158#endif /* ! _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H */
159