ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

---

IOInterruptEventSource

Overview

Event source for interrupt delivery to work-loop based drivers.

Discussion

The IOInterruptEventSource is a generic object that delivers calls interrupt routines in its client in a guaranteed single-threaded manner. IOInterruptEventSource is part of the IOKit IOWorkLoop infrastructure where the semantic that one and only one action method is executing within a work-loops event chain.

When the action method is called in the client member function will receive 2 arguments, (IOEventSource *) sender and (int) count (see Action), where sender will be a reference to the interrupt that occurred and the count will be computed by the difference between the producerCount and 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 statistics gathering.

In general a client will use the factory member function to create and initialize 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 IOWorkLoop.

An interrupt event source attaches itself to the given provider's interrupt source at initialization 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.

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 IOFilterInterruptEventSource would be a better choice.

Warning: All IOInterruptEventSources are created in the disabled state. If you want to actually schedule interrupt delivery do not forget to enable the source.

---

Functions

checkForWork

Pure Virtual member function used by IOWorkLoop for issuing a client call.

disable

Disables event source.

disableInterruptOccurred

Functions that get called by the interrupt controller (see IOService::registerInterrupt).

enable

Enables event source.

free

Subclass implementation of free method, disconnects from the interrupt source.

getAutoDisable

Get'ter for autoDisable variable.

getIntIndex

Get'ter for intIndex interrupt index variable.

getProvider

Get'ter for provider variable.

init

Primary initializer for the IOInterruptEventSource class.

interruptEventSource

Factory function for IOInterruptEventSources creation and initialization.

interruptOccurred

Functions that get called by the interrupt controller (see IOService::registerInterrupt).

normalInterruptOccurred

Functions that get called by the interrupt controller (see IOService::registerInterrupt).

---

checkForWork

---

Pure Virtual member function used by IOWorkLoop for issuing a client call.

protected

virtual bool checkForWork(); 

Return Value

Returns true if this function needs to be called again before all its outstanding events have been processed.

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.

---

disable

---

Disables event source.

public

virtual void disable(); 

Discussion

A subclass implementation is expected to respect the enabled state when checkForWork is called.

---

disableInterruptOccurred

---

Functions that get called by the interrupt controller (see IOService::registerInterrupt).

public

virtual void disableInterruptOccurred(
    void *,
    IOService *nub,
    int ind); 

Parameters

nub

Where the interrupt originated from.

ind

This interrupt's index within 'nub'.

---

enable

---

Enables event source.

public

virtual void enable(); 

Discussion

A subclass implementation is expected to respect the enabled state when checkForWork is called. Calling this function will cause the work loop to be signalled so that a checkForWork is performed.

---

free

---

Subclass implementation of free method, disconnects from the interrupt source.

protected

virtual void free(); 

---

getAutoDisable

---

Get'ter for autoDisable variable.

public

virtual bool getAutoDisable() const; 

Return Value

Returns the value of autoDisable.

---

getIntIndex

---

Get'ter for intIndex interrupt index variable.

public

virtual int getIntIndex() const; 

Return Value

Returns the value of intIndex.

---

getProvider

---

Get'ter for provider variable.

public

virtual const IOService *getProvider() const; 

Return Value

Returns the value of provider.

---

init

---

Primary initializer for the IOInterruptEventSource class.

public

virtual bool init(
    OSObject *owner, 
    Action action, 
    IOService *provider = 0, 
    int intIndex = 0); 

Parameters

owner

Owning client of the new event source.

action

C function to call when something happens.

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 interruptOccurred method explicitly. This will start the ball rolling for safe delivery of asynchronous events into the driver.

intIndex

The index of the interrupt within the provider's interrupt sources. Defaults to 0, i.e. the first interrupt in the provider.

Return Value

Returns true if the inherited classes and this instance initialize successfully.

---

interruptEventSource

---

Factory function for IOInterruptEventSources creation and initialization.

public

static IOInterruptEventSource * interruptEventSource(
    OSObject *owner, 
    Action action, 
    IOService *provider = 0, 
    int intIndex = 0); 

Parameters

owner

Owning client of the new event source.

action

C function to call when something happens.

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 interruptOccurred method explicitly. This will start the ball rolling for safe delivery of asynchronous events into the driver.

intIndex

The index of the interrupt within the provider's interrupt sources. Defaults to 0, i.e. the first interrupt in the provider.

Return Value

Returns a new interrupt event source if successfully created and initialized, 0 otherwise.

---

interruptOccurred

---

Functions that get called by the interrupt controller (see IOService::registerInterrupt).

public

virtual void interruptOccurred(
    void *,
    IOService *nub,
    int ind); 

Parameters

nub

Where the interrupt originated from.

ind

This interrupt's index within 'nub'.

---

normalInterruptOccurred

---

Functions that get called by the interrupt controller (see IOService::registerInterrupt).

public

virtual void normalInterruptOccurred(
    void *,
    IOService *nub,
    int ind); 

Parameters

nub

Where the interrupt originated from.

ind

This interrupt's index within 'nub'.

Typedefs

---

Action

---

public

typedef void ( *Action)(
    OSObject *,
    IOInterruptEventSource *,
    int count); 

Fields

owner

Pointer to client instance.

sender

Pointer to generation interrupt event source.

count

Number of interrupts seen before delivery.

Discussion

C pointer prototype of functions that are called in a single threaded context when an interrupt occurs.

Structs and Unions

---

ExpansionData

---

protected

struct ExpansionData {
}; 

Discussion

This structure will be used to expand the capablilties of the IOWorkLoop in the future.

Member Data

---

autoDisable

---

protected

bool autoDisable; 

Discussion

Do we need to automatically disable the interrupt source when we take an interrupt, i.e. we are level triggered.

---

consumerCount

---

protected

unsigned int consumerCount; 

Discussion

Current count of produced interrupts that the owner has been informed of.

---

explicitDisable

---

protected

bool explicitDisable; 

Discussion

Has the user expicitly disabled this event source, if so then do not override their request when returning from the callout.

---

intIndex

---

protected

int intIndex; 

---

producerCount

---

protected

volatile unsigned int producerCount; 

Discussion

Current count of produced interrupts that have been received.

---

provider

---

protected

IOService *provider; 

Discussion

IOService that provides interrupts for delivery.

---

reserved

---

protected

ExpansionData *reserved; 

Discussion

Reserved for future use. (Internal use only)

#defines

---

IOInterruptEventAction

---

#define IOInterruptEventAction IOInterruptEventSource::Action 

Discussion

Backward compatibilty define for the old non-class scoped type definition. See Action.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19