X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/de355530ae67247cbd0da700edb3a2a1dae884c2..813fb2f63a553c957e917ede5f119b021d6ce391:/iokit/IOKit/IOFilterInterruptEventSource.h

diff --git a/iokit/IOKit/IOFilterInterruptEventSource.h b/iokit/IOKit/IOFilterInterruptEventSource.h
index 0c554524c..13ef854d8 100644
--- a/iokit/IOKit/IOFilterInterruptEventSource.h
+++ b/iokit/IOKit/IOFilterInterruptEventSource.h
@@ -1,23 +1,29 @@
 /*
- * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 1998-2016 Apple Inc. All rights reserved.
  *
- * @APPLE_LICENSE_HEADER_START@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * 
- * The contents of this file constitute Original Code as defined in and
- * are subject to the Apple Public Source License Version 1.1 (the
- * "License").  You may not use this file except in compliance with the
- * License.  Please obtain a copy of the License at
- * http://www.apple.com/publicsource and read it before using this file.
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.
  * 
- * This Original Code and all software distributed under the License are
- * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this file.
+ * 
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
- * License for the specific language governing rights and limitations
- * under the License.
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
  * 
- * @APPLE_LICENSE_HEADER_END@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  */
 /*
 Copyright (c) 1999 Apple Computer, Inc.	 All rights reserved.
@@ -39,7 +45,9 @@ class IOService;
 <br><br>
     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.
 <br><br>
-    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.
+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.
+<br><br>
+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.
 */
 class IOFilterInterruptEventSource : public IOInterruptEventSource
 {
@@ -52,7 +60,7 @@ public:
     @param owner Pointer to the owning/client instance.
     @param sender Where is the interrupt comming from.
     @result false if this interrupt can be ignored. */
-    typedef bool (*Filter)(OSObject *, IOFilterInterruptEventSource *);
+    typedef bool (*Filter)(OSObject *owner, IOFilterInterruptEventSource *sender);
 
 /*! @defined IOFilterInterruptAction
     @discussion Backward compatibilty define for the old non-class scoped type definition.  See $link IOFilterInterruptSource::Filter */
@@ -63,7 +71,7 @@ private:
     virtual bool init(OSObject *inOwner,
 		      IOInterruptEventSource::Action inAction = 0,
 		      IOService *inProvider = 0,
-		      int inIntIndex = 0);
+		      int inIntIndex = 0) APPLE_KEXT_OVERRIDE;
 
     static IOInterruptEventSource *
 	interruptEventSource(OSObject *inOwner,
@@ -118,7 +126,7 @@ successfully.  */
 
 /*! @function signalInterrupt
     @abstract Cause the work loop to schedule the action.
-    @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 */
+    @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 */
     virtual void signalInterrupt();
 
 /*! @function getFilterAction
@@ -128,11 +136,11 @@ successfully.  */
 
 /*! @function normalInterruptOccurred
     @abstract Override $link IOInterruptEventSource::normalInterruptOccured to make a filter callout. */
-    virtual void normalInterruptOccurred(void *self, IOService *prov, int ind);
+    virtual void normalInterruptOccurred(void *self, IOService *prov, int ind) APPLE_KEXT_OVERRIDE;
 
 /*! @function disableInterruptOccurred
     @abstract Override $link IOInterruptEventSource::disableInterruptOccurred to make a filter callout. */
-    virtual void disableInterruptOccurred(void *self, IOService *prov, int ind);
+    virtual void disableInterruptOccurred(void *self, IOService *prov, int ind) APPLE_KEXT_OVERRIDE;
 
 private:
     OSMetaClassDeclareReservedUnused(IOFilterInterruptEventSource, 0);