iokit/IOKit/IOFilterInterruptEventSource.h

   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) 1999 Apple Computer, Inc.      All rights reserved.
  30  *
  31  *  HISTORY
  32  *   1999-4-15  Godfrey van der Linden(gvdl)
  33  *       Created.
  34  */
  35 #ifndef _IOKIT_IOFILTERINTERRUPTEVENTSOURCE_H
  36 #define _IOKIT_IOFILTERINTERRUPTEVENTSOURCE_H
  37
  38 #include <IOKit/IOInterruptEventSource.h>
  39
  40 class IOService;
  41
  42 /*! @class IOFilterInterruptEventSource : public IOInterruptEventSource
  43  *   @abstract Filtering varient of the $link IOInterruptEventSource.
  44  *   @discussion An interrupt event source that calls the client to determine if a interrupt event needs to be scheduled on the work loop.  A filter interrupt event source call's the client in the primary interrupt context, the client can then interrogate its hardware and determine if the interrupt needs to be processed yet.
  45  *  <br><br>
  46  *   As the routine is called in the primary interrupt context great care must be taken in the writing of this routine.  In general none of the generic IOKit environment is safe to call in this context.  We intend this routine to be used by hardware that can interrogate its registers without destroying state.  Primarily this variant of event sources will be used by drivers that share interrupts.  The filter routine will determine if the interrupt is a real interrupt or a ghost and thus optimise the work thread context switch away.
  47  *  <br><br>
  48  *  If you are implementing 'SoftDMA' (or pseudo-DMA), you may not want the I/O Kit to automatically start your interrupt handler routine on your work loop when your filter routine returns true.  In this case, you may choose to have your filter routine schedule the work on the work loop itself and then return false.  If you do this, the interrupt will not be disabled in hardware and you could receive additional primary interrupts before your work loop–level service routine completes.  Because this scheme has implications for synchronization between your filter routine and your interrupt service routine, you should avoid doing this unless your driver requires SoftDMA.
  49  *  <br><br>
  50  *  CAUTION:  Called in primary interrupt context, if you need to disable interrupt to guard you registers against an unexpected call then it is better to use a straight IOInterruptEventSource and its secondary interrupt delivery mechanism.
  51  */
  52 class IOFilterInterruptEventSource : public IOInterruptEventSource
  53 {
  54         OSDeclareDefaultStructors(IOFilterInterruptEventSource);
  55
  56 public:
  57 /*!
  58  *   @typedef Filter
  59  *   @discussion C Function pointer to a routine to call when an interrupt occurs.
  60  *   @param owner Pointer to the owning/client instance.
  61  *   @param sender Where is the interrupt comming from.
  62  *   @result false if this interrupt can be ignored. */
  63         typedef bool (*Filter)(OSObject *owner, IOFilterInterruptEventSource *sender);
  64
  65 /*! @defined IOFilterInterruptAction
  66  *   @discussion Backward compatibilty define for the old non-class scoped type definition.  See $link IOFilterInterruptSource::Filter */
  67 #define IOFilterInterruptAction IOFilterInterruptEventSource::Filter
  68
  69 #ifdef __BLOCKS__
  70         typedef bool (^FilterBlock)(IOFilterInterruptEventSource *sender);
  71 #endif /* __BLOCKS__ */
  72
  73 private:
  74 // Hide the superclass initializers
  75         virtual bool init(OSObject *inOwner,
  76             IOInterruptEventSource::Action inAction = NULL,
  77             IOService *inProvider = NULL,
  78             int inIntIndex = 0) APPLE_KEXT_OVERRIDE;
  79
  80         static IOInterruptEventSource *
  81         interruptEventSource(OSObject *inOwner,
  82             IOInterruptEventSource::Action inAction = NULL,
  83             IOService *inProvider = NULL,
  84             int inIntIndex = 0);
  85
  86 protected:
  87 /*! @var filterAction Filter callout */
  88
  89 #if XNU_KERNEL_PRIVATE
  90         union { Filter filterAction; FilterBlock filterActionBlock; };
  91 #else /* XNU_KERNEL_PRIVATE */
  92         Filter filterAction;
  93 #endif /* !XNU_KERNEL_PRIVATE */
  94
  95 /*! @struct ExpansionData
  96  *   @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  97  */
  98         struct ExpansionData { };
  99
 100 /*! @var reserved
 101  *   Reserved for future use.  (Internal use only)  */
 102         APPLE_KEXT_WSHADOW_PUSH;
 103         ExpansionData *reserved;
 104         APPLE_KEXT_WSHADOW_POP;
 105
 106 public:
 107 /*! @function filterInterruptEventSource
 108  *   @abstract Factor method to create and initialise an IOFilterInterruptEventSource.  See $link init.
 109  *   @param owner Owner/client of this event source.
 110  *   @param action 'C' Function to call when something happens.
 111  *   @param filter 'C' Function to call when interrupt occurs.
 112  *   @param provider Service that provides interrupts.
 113  *   @param intIndex Defaults to 0.
 114  *   @result a new event source if succesful, 0 otherwise.  */
 115         static IOFilterInterruptEventSource *
 116         filterInterruptEventSource(OSObject *owner,
 117             IOInterruptEventSource::Action action,
 118             Filter filter,
 119             IOService *provider,
 120             int intIndex = 0);
 121
 122 #ifdef __BLOCKS__
 123 /*! @function filterInterruptEventSource
 124  *   @abstract Factor method to create and initialise an IOFilterInterruptEventSource.  See $link init.
 125  *   @param owner Owner/client of this event source.
 126  *   @param provider Service that provides interrupts.
 127  *   @param intIndex The index of the interrupt within the provider's interrupt sources.
 128  *   @param action Block for the callout routine of this event source.
 129  *   @param filter Block to invoke when HW interrupt occurs.
 130  *   @result a new event source if succesful, 0 otherwise.  */
 131         static IOFilterInterruptEventSource *
 132         filterInterruptEventSource(OSObject *owner,
 133             IOService *provider,
 134             int intIndex,
 135             IOInterruptEventSource::ActionBlock action,
 136             FilterBlock filter);
 137 #endif /* __BLOCKS__ */
 138
 139 #if XNU_KERNEL_PRIVATE
 140         enum{
 141                 kFilterBlock = kSubClass0,
 142         };
 143 #endif
 144
 145 /*! @function init
 146  *   @abstract Primary initialiser for the IOFilterInterruptEventSource class.
 147  *   @param owner Owner/client of this event source.
 148  *   @param action 'C' Function to call when something happens.
 149  *   @param filter 'C' Function to call in primary interrupt context.
 150  *   @param provider Service that provides interrupts.
 151  *   @param intIndex Interrupt source within provider.  Defaults to 0.
 152  *   @result true if the inherited classes and this instance initialise
 153  *  successfully.  */
 154         virtual bool init(OSObject *owner,
 155             IOInterruptEventSource::Action action,
 156             Filter filter,
 157             IOService *provider,
 158             int intIndex = 0);
 159
 160         virtual void free( void ) APPLE_KEXT_OVERRIDE;
 161
 162 /*! @function signalInterrupt
 163  *   @abstract Cause the work loop to schedule the action.
 164  *   @discussion Cause the work loop to schedule the interrupt action even if the filter routine returns 'false'. Note well the interrupting condition MUST be cleared from the hardware otherwise an infinite process interrupt loop will occur.  Use this function when SoftDMA is desired.  See $link IOFilterInterruptSource::Filter */
 165         virtual void signalInterrupt();
 166
 167 /*! @function getFilterAction
 168  *   @abstract Get'ter for filterAction variable.
 169  *   @result value of filterAction. */
 170         virtual Filter getFilterAction() const;
 171
 172 #ifdef __BLOCKS__
 173 /*! @function getFilterActionBlock
 174  *   @abstract Get'ter for filterAction variable.
 175  *   @result value of filterAction. */
 176         FilterBlock getFilterActionBlock() const;
 177 #endif /* __BLOCKS__ */
 178
 179 /*! @function normalInterruptOccurred
 180  *   @abstract Override $link IOInterruptEventSource::normalInterruptOccured to make a filter callout. */
 181         virtual void normalInterruptOccurred(void *self, IOService *prov, int ind) APPLE_KEXT_OVERRIDE;
 182
 183 /*! @function disableInterruptOccurred
 184  *   @abstract Override $link IOInterruptEventSource::disableInterruptOccurred to make a filter callout. */
 185         virtual void disableInterruptOccurred(void *self, IOService *prov, int ind) APPLE_KEXT_OVERRIDE;
 186
 187 private:
 188         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 0);
 189         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 1);
 190         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 2);
 191         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 3);
 192         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 4);
 193         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 5);
 194         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 6);
 195         OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 7);
 196 };
 197
 198 #endif /* !_IOKIT_IOFILTERINTERRUPTEVENTSOURCE_H */