iokit/IOKit/IOInterruptEventSource.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23 Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  24
  25 HISTORY
  26     1998-7-13   Godfrey van der Linden(gvdl)
  27         Created.
  28     1998-10-30  Godfrey van der Linden(gvdl)
  29         Converted to C++
  30 */
  31
  32 #ifndef _IOKIT_IOINTERRUPTEVENTSOURCE_H
  33 #define _IOKIT_IOINTERRUPTEVENTSOURCE_H
  34
  35 #include <IOKit/IOEventSource.h>
  36
  37 class IOService;
  38
  39 /*! @class IOInterruptEventSource : public IOEventSource
  40     @abstract Event source for interrupt delivery to work-loop based drivers.
  41     @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.
  42 <br><br>
  43 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 occured 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.
  44 <br><br>
  45 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.
  46 <br><br>
  47 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.
  48 <br><br>
  49 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.
  50 <br><br>
  51 Warning:  All IOInterruptEventSources are created in the disabled state.  If you want to actually schedule interrupt delivery do not forget to enable the source.
  52 */
  53 class IOInterruptEventSource : public IOEventSource
  54 {
  55     OSDeclareDefaultStructors(IOInterruptEventSource)
  56
  57 public:
  58 /*! @typedef Action
  59     @discussion 'C' pointer prototype of functions that are called in a single threaded context when an interrupt occurs.
  60     @param owner Pointer to client instance.
  61     @param sender Pointer to generation interrupt event source.
  62     @param count Number of interrupts seen before delivery. */
  63     typedef void (*Action)(OSObject *, IOInterruptEventSource *, int count);
  64
  65 /*! @defined IOInterruptEventAction
  66     @discussion Backward compatibilty define for the old non-class scoped type definition.  See $link IOInterruptEventSource::Action */
  67 #define IOInterruptEventAction IOInterruptEventSource::Action
  68
  69 protected:
  70 /*! @var provider IOService that provides interrupts for delivery. */
  71     IOService *provider;
  72
  73 /*! @var intIndex */
  74     int intIndex;
  75
  76 /*! @var producerCount
  77     Current count of produced interrupts that have been received. */
  78     volatile unsigned int producerCount;
  79
  80 /*! @var consumerCount
  81     Current count of produced interrupts that the owner has been informed of. */
  82     unsigned int consumerCount;
  83
  84 /*! @var autoDisable Do we need to automatically disable the interrupt source when we take an interrupt, i.e. we are level triggered. */
  85     bool autoDisable;
  86
  87 /*! @var explicitDisable Has the user expicitly disabled this event source, if so then do not overide their request when returning from the callout */
  88     bool explicitDisable;
  89
  90 /*! @struct ExpansionData
  91     @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
  92     */
  93     struct ExpansionData { };
  94
  95 /*! @var reserved
  96     Reserved for future use.  (Internal use only)  */
  97     ExpansionData *reserved;
  98
  99 /*! @function free
 100     @abstract Sub-class implementation of free method, disconnects from the interrupt source. */
 101     virtual void free();
 102
 103 /*! @function checkForWork
 104     @abstract Pure Virtual member function used by IOWorkLoop for issueing a client calls.
 105     @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.
 106     @result Return true if this function needs to be called again before all its outstanding events have been processed. */
 107     virtual bool checkForWork();
 108
 109 public:
 110
 111 /*! @function interruptEventSource
 112     @abstract Factory function for IOInterruptEventSources creation and initialisation.
 113     @param owner Owning client of the new event source.
 114     @param action 'C' Function to call when something happens.
 115     @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.
 116     @param intIndex The index of the interrupt within the provider's interrupt sources.  Defaults to 0, i.e. the first interrupt in the provider.
 117     @result A new interrupt event source if successfully created and initialised, 0 otherwise.  */
 118     static IOInterruptEventSource *
 119         interruptEventSource(OSObject *owner,
 120                              Action action,
 121                              IOService *provider = 0,
 122                              int intIndex = 0);
 123
 124 /*! @function init
 125     @abstract Primary initialiser for the IOInterruptEventSource class.
 126     @param owner Owning client of the new event source.
 127     @param action 'C' Function to call when something happens.
 128     @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.
 129     @param intIndex The index of the interrupt within the provider's interrupt sources.  Defaults to 0, i.e. the first interrupt in the provider.
 130     @result true if the inherited classes and this instance initialise
 131 successfully.  */
 132     virtual bool init(OSObject *owner,
 133                       Action action,
 134                       IOService *provider = 0,
 135                       int intIndex = 0);
 136
 137 /*! @function enable
 138     @abstract Enable event source.
 139     @discussion A subclass implementation is expected to respect the enabled
 140 state when checkForWork is called.  Calling this function will cause the
 141 work-loop to be signalled so that a checkForWork is performed. */
 142     virtual void enable();
 143
 144 /*! @function disable
 145     @abstract Disable event source.
 146     @discussion A subclass implementation is expected to respect the enabled
 147 state when checkForWork is called. */
 148     virtual void disable();
 149
 150 /*! @function getProvider
 151     @abstract Get'ter for $link provider variable.
 152     @result value of provider. */
 153     virtual const IOService *getProvider() const;
 154
 155 /*! @function getIntIndex
 156     @abstract Get'ter for $link intIndex interrupt index variable.
 157     @result value of intIndex. */
 158     virtual int getIntIndex() const;
 159
 160 /*! @function getAutoDisable
 161     @abstract Get'ter for $link autoDisable variable.
 162     @result value of autoDisable. */
 163     virtual bool getAutoDisable() const;
 164
 165 /*! @function interruptOccurred
 166     @abstract Functions that get called by the interrupt controller. See $link IOService::registerInterrupt
 167     @param nub Where did the interrupt originate from
 168     @param ind What is this interrupts index within 'nub'. */
 169     virtual void interruptOccurred(void *, IOService *nub, int ind);
 170
 171 /*! @function normalInterruptOccurred
 172     @abstract Functions that get called by the interrupt controller.See $link IOService::registerInterrupt
 173     @param nub Where did the interrupt originate from
 174     @param ind What is this interrupts index within 'nub'. */
 175     virtual void normalInterruptOccurred(void *, IOService *nub, int ind);
 176
 177 /*! @function disableInterruptOccurred
 178     @abstract Functions that get called by the interrupt controller.See $link IOService::registerInterrupt
 179     @param nub Where did the interrupt originate from
 180     @param ind What is this interrupts index within 'nub'. */
 181     virtual void disableInterruptOccurred(void *, IOService *nub, int ind);
 182
 183 private:
 184     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 0);
 185     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 1);
 186     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 2);
 187     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 3);
 188     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 4);
 189     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 5);
 190     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 6);
 191     OSMetaClassDeclareReservedUnused(IOInterruptEventSource, 7);
 192 };
 193
 194 #endif /* !_IOKIT_IOINTERRUPTEVENTSOURCE_H */