iokit/DriverKit/IOInterruptDispatchSource.iig

   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
  35 struct IOInterruptDispatchSourcePayload {
  36         uint64_t time;
  37         uint64_t count;
  38 };
  39
  40 /*!
  41  * @class IOInterruptDispatchSource
  42  *
  43  * @abstract
  44  * IOInterruptDispatchSource delivers interrupts to a handler block on a dispatch queue.
  45  *
  46  * @discussion
  47  * A driver can run code in response to an interrupt from a device, specified as an IOService
  48  * and index. The code runs at normal thread level, but is notified with the mach_absolute_time
  49  * the primary interrupt fired. For IOPCIDevices, only MSI interrupt sources are supported.
  50  */
  51
  52 class NATIVE KERNEL IOInterruptDispatchSource : public IODispatchSource
  53 {
  54 public:
  55
  56     /*!
  57      * @brief       Create an IOInterruptDispatchSource for an interrupt by index from an IOService provider.
  58      * @param       provider The IOService object representing the HW device producing the interrupt.
  59      * @param       index Index for the interrupt.
  60      * @param       queue Target queue to run the handler block.
  61      * @param       source Created source with +1 retain count to be released by the caller.
  62      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  63      */
  64         static kern_return_t
  65         Create(IOService * provider,
  66             uint32_t index,
  67             IODispatchQueue * queue,
  68             IOInterruptDispatchSource ** source) LOCAL;
  69
  70         virtual bool
  71         init() override;
  72
  73         virtual void
  74         free() override;
  75
  76     /*!
  77      * @brief       Set the handler block to run when the interupt fires.
  78      * @param       action OSAction instance specifying the callback method. The OSAction object will be retained
  79      *              until SetHandler is called again or the event source is cancelled.
  80      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  81      */
  82         virtual kern_return_t
  83             SetHandler(
  84                 OSAction * action TYPE(InterruptOccurred)) LOCAL;
  85
  86     /*!
  87      * @brief       Control the enable state of the interrupt source.
  88      * @param       enable Pass true to enable the source or false to disable.
  89      * @param       handler Optional block to be executed after the interrupt has been disabled and any pending
  90      *              interrupt handlers completed.
  91      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  92      */
  93         virtual kern_return_t
  94         SetEnableWithCompletion(
  95                 bool enable,
  96                 IODispatchSourceCancelHandler handler) override LOCAL;
  97
  98     /*!
  99      * @brief       Cancel all callbacks from the event source.
 100      * @discussion  After cancellation, the source can only be freed. It cannot be reactivated.
 101      * @param       handler Handler block to be invoked after any callbacks have completed.
 102      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 103      */
 104         virtual kern_return_t
 105         Cancel(IODispatchSourceCancelHandler handler) override LOCAL;
 106
 107 private:
 108         virtual kern_return_t
 109         CheckForWork(bool synchronous) override LOCAL;
 110
 111         virtual void
 112         InterruptOccurred(
 113                 OSAction * action TARGET,
 114                 uint64_t   count,
 115                 uint64_t   time) REPLY LOCAL;
 116 };
 117
 118 #endif /* ! _IOKIT_UIOINTERRUPTDISPATCHSOURCE_H */