iokit/IOKit/IOFilterInterruptEventSource.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26 Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  27
  28 HISTORY
  29     1999-4-15   Godfrey van der Linden(gvdl)
  30         Created.
  31 */
  32 #ifndef _IOKIT_IOFILTERINTERRUPTEVENTSOURCE_H
  33 #define _IOKIT_IOFILTERINTERRUPTEVENTSOURCE_H
  34
  35 #include <IOKit/IOInterruptEventSource.h>
  36
  37 class IOService;
  38
  39 /*! @class IOFilterInterruptEventSource : public IOInterruptEventSource
  40     @abstract Filtering varient of the $link IOInterruptEventSource.
  41     @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.
  42 <br><br>
  43     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.
  44 <br><br>
  45     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.
  46 */
  47 class IOFilterInterruptEventSource : public IOInterruptEventSource
  48 {
  49     OSDeclareDefaultStructors(IOFilterInterruptEventSource)
  50
  51 public:
  52 /*!
  53     @typedef Filter
  54     @discussion C Function pointer to a routine to call when an interrupt occurs.
  55     @param owner Pointer to the owning/client instance.
  56     @param sender Where is the interrupt comming from.
  57     @result false if this interrupt can be ignored. */
  58     typedef bool (*Filter)(OSObject *, IOFilterInterruptEventSource *);
  59
  60 /*! @defined IOFilterInterruptAction
  61     @discussion Backward compatibilty define for the old non-class scoped type definition.  See $link IOFilterInterruptSource::Filter */
  62 #define IOFilterInterruptAction IOFilterInterruptEventSource::Filter
  63
  64 private:
  65     // Hide the superclass initializers
  66     virtual bool init(OSObject *inOwner,
  67                       IOInterruptEventSource::Action inAction = 0,
  68                       IOService *inProvider = 0,
  69                       int inIntIndex = 0);
  70
  71     static IOInterruptEventSource *
  72         interruptEventSource(OSObject *inOwner,
  73                              IOInterruptEventSource::Action inAction = 0,
  74                              IOService *inProvider = 0,
  75                              int inIntIndex = 0);
  76
  77 protected:
  78 /*! @var filterAction Filter callout */
  79     Filter filterAction;
  80
  81 /*! @struct ExpansionData
  82     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  83     */
  84     struct ExpansionData { };
  85
  86 /*! @var reserved
  87     Reserved for future use.  (Internal use only)  */
  88     ExpansionData *reserved;
  89
  90 public:
  91 /*! @function filterInterruptEventSource
  92     @abstract Factor method to create and initialise an IOFilterInterruptEventSource.  See $link init.
  93     @param owner Owner/client of this event source.
  94     @param action 'C' Function to call when something happens.
  95     @param filter 'C' Function to call when interrupt occurs.
  96     @param provider Service that provides interrupts.
  97     @param intIndex Defaults to 0.
  98     @result a new event source if succesful, 0 otherwise.  */
  99     static IOFilterInterruptEventSource *
 100         filterInterruptEventSource(OSObject *owner,
 101                                    IOInterruptEventSource::Action action,
 102                                    Filter filter,
 103                                    IOService *provider,
 104                                    int intIndex = 0);
 105
 106 /*! @function init
 107     @abstract Primary initialiser for the IOFilterInterruptEventSource class.
 108     @param owner Owner/client of this event source.
 109     @param action 'C' Function to call when something happens.
 110     @param filter 'C' Function to call in primary interrupt context.
 111     @param provider Service that provides interrupts.
 112     @param intIndex Interrupt source within provider.  Defaults to 0.
 113     @result true if the inherited classes and this instance initialise
 114 successfully.  */
 115     virtual bool init(OSObject *owner,
 116                       IOInterruptEventSource::Action action,
 117                       Filter filter,
 118                       IOService *provider,
 119                       int intIndex = 0);
 120
 121
 122 /*! @function signalInterrupt
 123     @abstract Cause the work loop to schedule the action.
 124     @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 */
 125     virtual void signalInterrupt();
 126
 127 /*! @function getFilterAction
 128     @abstract Get'ter for filterAction variable.
 129     @result value of filterAction. */
 130     virtual Filter getFilterAction() const;
 131
 132 /*! @function normalInterruptOccurred
 133     @abstract Override $link IOInterruptEventSource::normalInterruptOccured to make a filter callout. */
 134     virtual void normalInterruptOccurred(void *self, IOService *prov, int ind);
 135
 136 /*! @function disableInterruptOccurred
 137     @abstract Override $link IOInterruptEventSource::disableInterruptOccurred to make a filter callout. */
 138     virtual void disableInterruptOccurred(void *self, IOService *prov, int ind);
 139
 140 private:
 141     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 0);
 142     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 1);
 143     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 2);
 144     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 3);
 145     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 4);
 146     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 5);
 147     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 6);
 148     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 7);
 149 };
 150
 151 #endif /* !_IOKIT_IOFILTERINTERRUPTEVENTSOURCE_H */