Mac Developer Library

Developer

IOService Class Reference

Options
Deployment Target:

On This Page
Language:

IOService

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

The base class for most I/O Kit families, devices, and drivers.

The IOService base class defines APIs used to publish services, instantiate other services based on the existance of a providing service (ie. driver stacking), destroy a service and its dependent stack, notify interested parties of service state changes, and general utility functions useful across all families.

Types of service are specified with a matching dictionary that describes properties of the service. For example, a matching dictionary might describe any IOUSBDevice (or subclass), an IOUSBDevice with a certain class code, or a IOPCIDevice with a set of matching names or device & vendor IDs. Since the matching dictionary is interpreted by the family which created the service, as well as generically by IOService, the list of properties considered for matching depends on the familiy.

Matching dictionaries are associated with IOService classes by the catalogue, as driver property tables, and also supplied by clients of the notification APIs.

IOService provides matching based on C++ class (via OSMetaClass dynamic casting), registry entry name, a registry path to the service (which includes device tree paths), a name assigned by BSD, or by its location (its point of attachment).

Driver Instantiation by IOService

Drivers are subclasses of IOService, and their availability is managed through the catalogue. They are instantiated based on the publication of an IOService they use (for example, an IOPCIDevice or IOUSBDevice), or when they are added to the catalogue and the IOService(s) they use are already available.

When an IOService (the "provider") is published with the registerService method, the matching and probing process begins, which is always single threaded per provider. A list of matching dictionaries from the catalog and installed publish notification requests, that successfully match the IOService, is constructed, with ordering supplied by kIOProbeScoreKey ("IOProbeScore") property in the dictionary, or supplied with the notification.

Each entry in the list is then processed in order - for notifications, the notification is delivered, for driver property tables a lot more happens.

The driver class is instantiated and init() called with its property table. The new driver instance is then attached to the provider, and has its probe method called with the provider as an argument. The default probe method does nothing but return success, but a driver may implement this method to interrogate the provider to make sure it can work with it. It may also modify its probe score at this time. After probe, the driver is detached and the next in the list is considered (ie. attached, probed, and detached).

When the probing phase is complete, the list consists of successfully probed drivers, in order of their probe score (after adjustment during the probe call). The list is then divided into categories based on the kIOMatchCategoryKey property ("IOMatchCategory"); drivers without a match category are all considered in one default category. Match categories allow multiple clients of a provider to be attached and started, though the provider may also enforce open/close semantics to gain active access to it.

For each category, the highest scoring driver in that category is attached to the provider, and its start method called. If start is successful, the rest of the drivers in the same match category are discarded, otherwise the next highest scoring driver is started, and so on.

The driver should only consider itself in action when the start method is called, meaning it has been selected for use on the provider, and consuming that particular match category. It should also be prepared to be allocated, probed and freed even if the probe was successful.

After the drivers have all synchronously been started, the installed "matched" notifications that match the registered IOService are delivered.

Properties used by IOService

kIOClassKey, extern const OSSymbol * gIOClassKey, "IOClass"

Class of the driver to instantiate on matching providers.

kIOProviderClassKey, extern const OSSymbol * gIOProviderClassKey, "IOProviderClass"

Class of the provider(s) to be considered for matching, checked with OSDynamicCast so subclasses will also match.

kIOProbeScoreKey, extern const OSSymbol * gIOProbeScoreKey, "IOProbeScore"

The probe score initially used to order multiple matching drivers.

kIOMatchCategoryKey, extern const OSSymbol * gIOMatchCategoryKey, "IOMatchCategory"

A string defining the driver category for matching purposes. All drivers with no IOMatchCategory property are considered to be in the same default category. Only one driver in a category can be started on each provider.

kIONameMatchKey, extern const OSSymbol * gIONameMatchKey, "IONameMatch"

A string or collection of strings that match the provider's name. The comparison is implemented with the IORegistryEntry::compareNames method, which supports a single string, or any collection (OSArray, OSSet, OSDictionary etc.) of strings. IOService objects with device tree properties (eg. IOPCIDevice) will also be matched based on that standard's "compatible", "name", "device_type" properties. The matching name will be left in the driver's property table in the kIONameMatchedKey property.

Examples

  • <key>IONameMatch</key>
  • <string>pci106b,7</string>

For a list of possible matching names, a serialized array of strings should used, eg.

  • <key>IONameMatch</key>
  • <array>
  • <string>APPL,happy16</string>
  • <string>pci106b,7</string>
  • </array>

kIONameMatchedKey, extern const OSSymbol * gIONameMatchedKey, "IONameMatched"

The name successfully matched name from the kIONameMatchKey property will be left in the driver's property table as the kIONameMatchedKey property.

kIOPropertyMatchKey, extern const OSSymbol * gIOPropertyMatchKey, "IOPropertyMatch"

A dictionary of properties that each must exist in the matching IOService and compare successfully with the isEqualTo method.

  • <key>IOPropertyMatch</key>
  • <dictionary>
  • <key>APPL,happy16</key>
  • <string>APPL,meek8</string>
  • </dictionary>

kIOUserClientClassKey, extern const OSSymbol * gIOUserClientClassKey, "IOUserClientClass"

The class name that the service will attempt to allocate when a user client connection is requested. First the device nub is queried, then the nub's provider is queried by default.

kIOKitDebugKey, extern const OSSymbol * gIOKitDebugKey, "IOKitDebug"

Set some debug flags for logging the driver loading process. Flags are defined in IOKit/IOKitDebug.h, but 65535 works well.

  • Acknowledges an in-progress power state change.

    Declaration

    C++

    IOReturn acknowledgePowerChange( IOService *whichDriver );

    Parameters

    whichDriver

    A pointer to the calling driver. The called object tracks all interested parties to ensure that all have acknowledged the power state change.

    Return Value

    IOPMNoErr.

    Discussion

    When power management informs an interested object (via powerStateWillChangeTo or powerStateDidChangeTo), the object can return an immediate acknowledgement via a return code, or it may return an indication that it will acknowledge later by calling acknowledgePowerChange. Interested objects are those that have registered as interested drivers, as well as power plane children of the power changing driver. A driver that calls registerInterestedDriver must call acknowledgePowerChange, or use an immediate acknowledgement return from powerStateWillChangeTo or powerStateDidChangeTo.

  • Acknowledges the belated completion of a driver's setPowerState power state change.

    Declaration

    C++

    IOReturn acknowledgeSetPowerState( void );

    Return Value

    IOPMNoErr.

    Discussion

    After power management instructs a driver to change its state via setPowerState, that driver must acknowledge the change when its device has completed its transition. The acknowledgement may be immediate, via a return code from setPowerState, or delayed, via this call to acknowledgeSetPowerState. Any driver that does not return kIOPMAckImplied from its setPowerState implementation must later call acknowledgeSetPowerState.

  • Informs power management when a power-managed device is in use, so that power management can track when it is idle and adjust its power state accordingly.

    Declaration

    C++

    virtual bool activityTickle( unsigned long type, unsigned long stateNumber = 0 );

    Parameters

    type

    When type is kIOPMSubclassPolicy, activityTickle is not handled in IOService and should be intercepted by the subclass. When type is kIOPMSuperclassPolicy1, an activity flag is set and the device state is checked. If the device has been powered down, it is powered up again.

    stateNumber

    When type is kIOPMSuperclassPolicy1, stateNumber contains the desired power state ordinal for the activity. If the device is in a lower state, the superclass will switch it to this state. This is for devices that can handle some accesses in lower power states; the device is powered up only as far as it needs to be for the activity.

    Return Value

    When type is kIOPMSuperclassPolicy1, the superclass returns true if the device is currently in the state specified by stateNumber. If the device is in a lower state and must be powered up, the superclass returns false; in this case the superclass will initiate a power change to power the device up.

    Discussion

    The activityTickle method is provided for objects in the system (or for the driver itself) to tell a driver that its device is being used. The IOService superclass can manage idleness determination with a simple idle timer mechanism and this activityTickle call. To start this up, the driver calls its superclass's setIdleTimerPeriod. This starts a timer for the time interval specified in the call. When the timer expires, the superclass checks to see if there has been any activity since the last timer expiration. (It checks to see if activityTickle has been called). If there has been activity, it restarts the timer, and this process continues. When the timer expires, and there has been no device activity, the superclass lowers the device power state to the next lower state. This can continue until the device is in state zero. After the device has been powered down by at least one power state, a subsequent call to activityTickle causes the device to be switched to a higher state required for the activity. If the driver is managing the idleness determination totally on its own, the value of the type parameter should be kIOPMSubclassPolicy, and the driver should override the activityTickle method. The superclass IOService implementation of activityTickle does nothing with the kIOPMSubclassPolicy argument.

  • Adds a location matching property to an existing dictionary.

    Declaration

    C++

    static OSDictionary * addLocation( OSDictionary *table );

    Parameters

    table

    The matching properties are added to the specified dictionary, which must be non-zero.

    Return Value

    The location matching dictionary created is returned on success, or zero on failure.

    Discussion

    This function creates matching properties that specify the location of a IOService object, as an embedded matching dictionary. This matching will be successful on an IOService object that attached to an IOService object which matches this location matching dictionary.

  • Adds a persistant notification handler to be notified of IOService events.

    Declaration

    C++

    static IONotifier * addMatchingNotification( const OSSymbol *type, OSDictionary *matching, IOServiceMatchingNotificationHandler handler, void *target, void *ref = 0, SInt32 priority = 0 );

    Parameters

    type

    An OSSymbol identifying the type of notification and IOService state:

    gIOPublishNotification Delivered when an IOService object is registered.

    gIOFirstPublishNotification Delivered when an IOService object is registered, but only once per IOService instance. Some IOService objects may be reregistered when their state is changed.

    gIOMatchedNotification Delivered when an IOService object has been matched with all client drivers, and they have been probed and started.

    gIOFirstMatchNotification Delivered when an IOService object has been matched with all client drivers, but only once per IOService instance. Some IOService objects may be reregistered when their state is changed.

    gIOTerminatedNotification Delivered after an IOService object has been terminated, during its finalize stage.

    matching

    A matching dictionary to restrict notifications to only matching IOService objects. The dictionary is retained while the notification is installed. (Differs from addNotification).

    handler

    A C function callback to deliver notifications.

    target

    An instance reference for the callback's use.

    ref

    A reference constant for the callback's use.

    priority

    A constant ordering all notifications of a each type.

    Return Value

    An instance of an IONotifier object that can be used to control or destroy the notification request.

    Discussion

    IOService will deliver notifications of changes in state of an IOService object to registered clients. The type of notification is specified by a symbol, for example gIOMatchedNotification or gIOTerminatedNotification, and notifications will only include IOService objects that match the supplied matching dictionary. Notifications are ordered by a priority set with addNotification. When the notification is installed, its handler will be called with each of any currently existing IOService objects that are in the correct state (eg. registered) and match the supplied matching dictionary, avoiding races between finding preexisting and new IOService events. The notification request is identified by an instance of an IONotifier object, through which it can be enabled, disabled, or removed. addMatchingNotification does not consume a reference on the matching dictionary when the notification is removed, unlike addNotification.

  • Deprecated use addMatchingNotification(). Adds a persistant notification handler to be notified of IOService events.

    Declaration

    C++

    static IONotifier * addNotification( const OSSymbol *type, OSDictionary *matching, IOServiceNotificationHandler handler, void *target, void *ref = 0, SInt32 priority = 0 ) __attribute__((deprecated));

    Parameters

    type

    An OSSymbol identifying the type of notification and IOService state:

    gIOPublishNotification Delivered when an IOService object is registered.

    gIOFirstPublishNotification Delivered when an IOService object is registered, but only once per IOService instance. Some IOService objects may be reregistered when their state is changed.

    gIOMatchedNotification Delivered when an IOService object has been matched with all client drivers, and they have been probed and started.

    gIOFirstMatchNotification Delivered when an IOService object has been matched with all client drivers, but only once per IOService instance. Some IOService objects may be reregistered when their state is changed.

    gIOTerminatedNotification Delivered after an IOService object has been terminated, during its finalize stage.

    matching

    A matching dictionary to restrict notifications to only matching IOService objects. The dictionary will be released when the notification is removed, consuming the passed-in reference.

    handler

    A C function callback to deliver notifications.

    target

    An instance reference for the callback's use.

    ref

    A reference constant for the callback's use.

    priority

    A constant ordering all notifications of a each type.

    Return Value

    An instance of an IONotifier object that can be used to control or destroy the notification request.

    Discussion

    IOService will deliver notifications of changes in state of an IOService object to registered clients. The type of notification is specified by a symbol, for example gIOMatchedNotification or gIOTerminatedNotification, and notifications will only include IOService objects that match the supplied matching dictionary. Notifications are ordered by a priority set with addNotification. When the notification is installed, its handler will be called with each of any currently existing IOService objects that are in the correct state (eg. registered) and match the supplied matching dictionary, avoiding races between finding preexisting and new IOService events. The notification request is identified by an instance of an IONotifier object, through which it can be enabled, disabled, or removed. addNotification consumes a retain count on the matching dictionary when the notification is removed.

  • Informs a driver that it has a new child.

    Declaration

    C++

    virtual IOReturn addPowerChild( IOService *theChild );

    Parameters

    theChild

    A pointer to the child IOService object.

    Discussion

    The Platform Expert uses this method to call a driver and introduce it to a new child. This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Adjusts the busyState of an IOService object.

    Declaration

    C++

    virtual void adjustBusy( SInt32delta );

    Parameters

    delta

    The delta to be applied to the IOService object's busyState.

    Discussion

    Applies a delta to an IOService object's busyState. A change in the busyState to or from zero will change the IOService object's provider's busyState by one (in the same direction).

  • Attaches an IOService client to a provider in the I/O Registry.

    Declaration

    C++

    virtual bool attach( IOService *provider );

    Parameters

    provider

    The IOService object which will serve as this object's provider.

    Return Value

    false if the provider is inactive or on a resource failure; otherwise true.

    Discussion

    This function called in an IOService client enters the client into the I/O Registry as a child of the provider in the service plane. The provider must be active or the attach will fail. Multiple attach calls to the same provider are no-ops and return success. A client may be attached to multiple providers. Entering an object into the I/O Registry retains both the client and provider until they are detached.

  • Calls the platform function with the given name.

    Declaration

    C++

    virtual IOReturn callPlatformFunction( const OSSymbol *functionName, bool waitForFunction, void *param1, void *param2, void *param3, void *param4 );

    Parameters

    functionName

    Name of the function to be called. When functionName is a C string, callPlatformFunction converts the C string to an OSSymbol and calls the OSSymbol version of callPlatformFunction. This process can block and should not be used from an interrupt context.

    waitForFunction

    If true, callPlatformFunction will not return until the function has been called.

    Return Value

    An IOReturn code; kIOReturnSuccess if the function was successfully executed, kIOReturnUnsupported if a service to execute the function could not be found. Other return codes may be returned by the function.

    Discussion

    The platform expert or other drivers may implement various functions to control hardware features. callPlatformFunction allows any IOService object to access these functions. Normally callPlatformFunction is called on a service's provider. The provider services the request or passes it to its provider. The system's IOPlatformExpert subclass catches functions it knows about and redirects them into other parts of the service plane. If the IOPlatformExpert subclass cannot execute the function, the base class is called. The IOPlatformExpert base class attempts to find a service to execute the function by looking up the function name in an IOResources name space. A service may publish a service using publishResource(functionName, this). If no service can be found to execute the function an error is returned.

  • Causes a device interrupt to occur.

    Declaration

    C++

    virtual IOReturn causeInterrupt( intsource);

    Parameters

    source

    The index of the interrupt source in the device.

    Return Value

    An IOReturn code (kIOReturnNoInterrupt is returned if the source is not valid).

    Discussion

    Emulates a hardware interrupt, to be called from task level.

  • Sets a driver's power state.

    Declaration

    C++

    IOReturn changePowerStateTo( unsigned longordinal );

    Parameters

    ordinal

    The number of the desired power state in the power state array.

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    This function is one of several that are used to set a driver's power state. In most circumstances, however, you should call changePowerStateToPriv instead. Calls to changePowerStateTo, changePowerStateToPriv, and a driver's power children all affect the power state of a driver. For legacy design reasons, they have overlapping functionality. Although you should call changePowerStateToPriv to change your device's power state, you might need to call changePowerStateTo in the following circumstances:

    • If a driver will be using changePowerStateToPriv to change its power state, it should call changePowerStateTo(0) in its start routine to eliminate the influence changePowerStateTo has on power state calculations.

    • Call changePowerStateTo in conjunction with setIdleTimerPeriod and activityTickle to idle a driver into a low power state. For a driver with 3 power states, for example, changePowerStateTo(1) sets a minimum level of power state 1, such that the idle timer period may not set your device's power any lower than state 1.

  • Tells a driver's superclass to change the power state of its device.

    Declaration

    C++

    IOReturn changePowerStateToPriv( unsigned longordinal );

    Parameters

    ordinal

    The number of the desired power state in the power state array.

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    A driver uses this method to tell its superclass to change the power state of the device. This is the recommended way to change the power state of a device. Three things affect driver power state: changePowerStateTo, changePowerStateToPriv, and the desires of the driver's power plane children. Power management puts the device into the maximum state governed by those three entities. Drivers may eliminate the influence of the changePowerStateTo method on power state one of two ways. See powerOverrideOnPriv to ignore the method's influence, or call changePowerStateTo(0) in the driver's start routine to remove the changePowerStateTo method's power request.

  • Deprecated. Do not use.

    Declaration

    C++

    virtual void clampPowerOn( unsigned long duration );

  • Releases active access to a provider.

    Declaration

    C++

    virtual void close( IOService *forClient, IOOptionBits options = 0 );

    Parameters

    forClient

    Designates the client of the provider requesting the close.

    options

    Options available for the close. The provider family may implement options for close; IOService defines none.

    arg

    Family specific arguments which are ignored by IOService.

    Discussion

    IOService provides generic open and close semantics to track clients of a provider that have established an active datapath. The use of open and close, and rules regarding ownership are family defined, and defined by the handleOpen and handleClose methods in the provider.

  • Declaration

    C++

    virtual void command_received( void *, void *, void *, void *);

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Compares a set of properties in a matching dictionary with an IOService object's property table.

    Declaration

    C++

    virtual bool compareProperties( OSDictionary *matching, OSCollection *keys );

    Parameters

    matching

    The matching dictionary, which must be non-zero.

    keys

    A collection (eg. OSSet, OSArray, OSDictionary) which should contain OSStrings (or OSSymbols) that specify the property keys to be compared.

    Return Value

    Success if compareProperty returns true for each key in the collection; otherwise failure.

    Discussion

    This is a helper function to aid in implementing matchPropertyTable. A collection of dictionary keys specifies properties in a matching dictionary to be compared, with compareProperty, with an IOService object's property table, if compareProperty returns true for each key, success is returned; otherwise failure.

  • Compares a property in a matching dictionary with an IOService object's property table.

    Declaration

    C++

    virtual bool compareProperty( OSDictionary *matching, const char *key );

    Parameters

    matching

    The matching dictionary, which must be non-zero.

    key

    The dictionary key specifying the property to be compared, as a C string.

    Return Value

    true if the property does not exist in the matching table. If the property exists in the matching dictionary but not the IOService property table, failure is returned. Otherwise the result of calling the property from the matching dictionary's isEqualTo method with the IOService property as an argument is returned.

    Discussion

    This is a helper function to aid in implementing matchPropertyTable. If the property specified by key exists in the matching dictionary, it is compared with a property of the same name in the IOService object's property table. The comparison is performed with the isEqualTo method. If the property does not exist in the matching table, success is returned. If the property exists in the matching dictionary but not the IOService property table, failure is returned.

  • Compares a property in a matching dictionary with an IOService object's property table.

    Declaration

    C++

    virtual bool compareProperty( OSDictionary *matching, const OSString *key );

    Parameters

    matching

    The matching dictionary, which must be non-zero.

    key

    The dictionary key specifying the property to be compared, as an OSString (which includes OSSymbol).

    Return Value

    true if the property does not exist in the matching table. If the property exists in the matching dictionary but not the IOService property table, failure is returned. Otherwise the result of calling the property from the matching dictionary's isEqualTo method with the IOService property as an argument is returned.

    Discussion

    This is a helper function to aid in implementing matchPropertyTable. If the property specified by key exists in the matching dictionary, it is compared with a property of the same name in the IOService object's property table. The comparison is performed with the isEqualTo method. If the property does not exist in the matching table, success is returned. If the property exists in the matching dictionary but not the IOService property table, failure is returned.

  • configure IOReporting channels

    Declaration

    C++

    virtual IOReturn configureReport( IOReportChannelList *channels, IOReportConfigureActionaction, void *result, void *destination);

    Parameters

    channels

    - channels to configure

    action

    - enable/disable/size, etc

    result

    - action-specific returned value

    destination

    - action-specific default destination

  • Declaration

    C++

    virtual IOService * copyClientWithCategory( const OSSymbol *category );

    Parameters

    category

    An OSSymbol corresponding to an IOMatchCategory matching property.

    Return Value

    Returns a reference to the IOService child with the given category. The result should be released by the caller.

  • Finds one of the current published IOService objects matching a matching dictionary.

    Declaration

    C++

    static IOService * copyMatchingService( OSDictionary *matching );

    Parameters

    matching

    The matching dictionary describing the desired IOService object.

    Return Value

    The IOService object or NULL. To be released by the caller.

    Discussion

    Provides a method to find one member of the set of published IOService objects matching the supplied matching dictionary.

  • Finds out the capability of a device's current power state.

    Declaration

    C++

    IOPMPowerFlags currentCapability( void );

    Return Value

    A copy of the capabilityFlags field for the current power state in the power state array.

  • Finds out the current power consumption of a device.

    Declaration

    C++

    unsigned long currentPowerConsumption( void );

    Return Value

    A copy of the staticPower field for the current power state in the power state array.

    Discussion

    Most Mac OS X power managed drivers do not report their power consumption via the staticPower field. Thus this call will not accurately reflect power consumption for most drivers.

  • De-registers power state interest from a previous call to registerInterestedDriver.

    Declaration

    C++

    IOReturn deRegisterInterestedDriver( IOService *theDriver );

    Parameters

    theDriver

    The interested driver previously passed into registerInterestedDriver.

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    The retain from registerInterestedDriver is released. This method is synchronous against any powerStateWillChangeTo or powerStateDidChangeTo call targeting the interested driver, so when this method returns it is guaranteed those interest handlers will not be entered. Most drivers do not need to override deRegisterInterestedDriver.

  • Detaches an IOService client from a provider in the I/O Registry.

    Declaration

    C++

    virtual void detach( IOService *provider );

    Parameters

    provider

    The IOService object to detach from.

    Discussion

    This function called in an IOService client removes the client as a child of the provider in the service plane of the I/O Registry. If the provider is not a parent of the client this is a no-op, otherwise the I/O Registry releases both the client and provider.

  • Passes a termination up the stack.

    Declaration

    C++

    virtual bool didTerminate( IOService *provider, IOOptionBitsoptions, bool *defer );

    Parameters

    provider

    The terminated provider of this object.

    options

    Options originally passed to terminate.

    defer

    If there is pending I/O that requires this object to persist, and the provider is not opened by this object set defer to true and call the IOService::didTerminate() implementation when the I/O completes. Otherwise, leave defer set to its default value of false.

    Return Value

    true.

    Discussion

    Notification that a provider has been terminated, sent after recursing up the stack, in leaf-to-root order.

  • Asks a driver if its device is the one that just woke the system from sleep.

    Declaration

    C++

    virtual bool didYouWakeSystem( void ) __attribute__((deprecated));

    Return Value

    true if the driver's device woke the system and false otherwise.

    Discussion

    Power management calls a power managed driver with this method to ask if its device is the one that just woke the system from sleep. If a device is capable of waking the system from sleep, its driver should implement didYouWakeSystem and return true if its device was responsible for waking the system.

  • Synchronously disables a device interrupt.

    Declaration

    C++

    virtual IOReturn disableInterrupt( intsource);

    Parameters

    source

    The index of the interrupt source in the device.

    Return Value

    An IOReturn code (kIOReturnNoInterrupt is returned if the source is not valid).

    Discussion

    If the interrupt routine is running, the call will block until the routine completes. It is the caller's responsiblity to keep track of the enable state of the interrupt source.

  • Enables a device interrupt.

    Declaration

    C++

    virtual IOReturn enableInterrupt( intsource);

    Parameters

    source

    The index of the interrupt source in the device.

    Return Value

    An IOReturn code (kIOReturnNoInterrupt is returned if the source is not valid).

    Discussion

    It is the caller's responsiblity to keep track of the enable state of the interrupt source.

  • Translates an IOReturn code to a BSD errno.

    Declaration

    C++

    virtual int errnoFromReturn( IOReturnrtn );

    Parameters

    rtn

    The IOReturn code.

    Return Value

    The BSD errno or EIO if unknown.

    Discussion

    BSD defines its own return codes for its functions in sys/errno.h, and I/O Kit families may need to supply compliant results in BSD shims. Results are available for the standard return codes in IOReturn.h in IOService, while subclasses may implement this method to interpret family dependent return codes.

  • Finalizes the destruction of an IOService object.

    Declaration

    C++

    virtual bool finalize( IOOptionBitsoptions );

    Parameters

    options

    The options passed to the terminate method of the IOService object are passed on to finalize.

    Return Value

    true.

    Discussion

    The finalize method is called in an inactive (ie. terminated) IOService object after the last client has detached. IOService's implementation will call stop, close, and detach on each provider. When finalize returns, the object's retain count will have no references generated by IOService's registration process.

  • Frees data structures that were allocated when power management was initialized on this service.

    Declaration

    C++

    virtual void free( void );

  • Returns the current aggressiveness value for the given type.

    Declaration

    C++

    virtual IOReturn getAggressiveness( unsigned longtype, unsigned long *currentLevel );

    Parameters

    type

    The aggressiveness factor to query.

    currentLevel

    Upon successful return, contains the value of aggressiveness factor type.

    Return Value

    kIOReturnSuccess upon success; an I/O Kit error code otherwise.

  • Returns the busyState of an IOService object.

    Declaration

    C++

    virtual UInt32 getBusyState( void );

    Return Value

    The busyState value.

    Discussion

    Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService object, its busyState is increased by one. Change in busyState to or from zero also changes the IOService object's provider's busyState by one, which means that an IOService object is marked busy when any of the above activities is ocurring on it or any of its clients.

  • Returns an IOService object's primary client.

    Declaration

    C++

    virtual IOService * getClient( void ) const;

    Return Value

    The first client of the provider, or zero if the IOService object is not attached into the I/O Registry. The client is retained while it is attached, and should not be released by the caller.

    Discussion

    This function called in an IOService provider will return the first client to attach to it. For IOService objects which have only only one client, this may be a useful simplification.

  • Returns an iterator over an IOService object's clients.

    Declaration

    C++

    virtual OSIterator * getClientIterator( void ) const;

    Return Value

    An iterator over the clients of the provider, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, though they may no longer be attached during the iteration.

    Discussion

    For IOService objects that may have multiple clients, this method supplies an iterator over a provider's clients.

  • Returns the array of IODeviceMemory objects representing a device's memory mapped ranges.

    Declaration

    C++

    virtual OSArray * getDeviceMemory( void );

    Return Value

    An OSArray of IODeviceMemory objects, or zero if none are available. The array is retained by the provider, so is valid while attached.

    Discussion

    This method returns an array of IODeviceMemory objects representing the physical memory ranges allocated to a memory mapped device.

  • Returns a count of the physical memory ranges available for a device.

    Declaration

    C++

    virtual IOItemCount getDeviceMemoryCount( void );

    Return Value

    An integer count of the number of ranges available.

    Discussion

    This method returns the count of physical memory ranges, each represented by an IODeviceMemory instance, that have been allocated for a memory mapped device.

  • Returns an instance of IODeviceMemory representing one of a device's memory mapped ranges.

    Declaration

    C++

    virtual IODeviceMemory * getDeviceMemoryWithIndex( unsigned intindex );

    Parameters

    index

    An index into the array of ranges assigned to the device.

    Return Value

    A pointer to an instance of IODeviceMemory, or zero if the index is beyond the count available. The IODeviceMemory is retained by the provider, so is valid while attached, or while any mappings to it exist. It should not be released by the caller. See also mapDeviceMemoryWithIndex, which creates a device memory mapping.

    Discussion

    This method returns a pointer to an instance of IODeviceMemory for the physical memory range at the given index for a memory mapped device.

  • Returns the type of interrupt used for a device supplying hardware interrupts.

    Declaration

    C++

    virtual IOReturn getInterruptType( intsource, int *interruptType);

    Parameters

    source

    The index of the interrupt source in the device.

    interruptType

    The interrupt type for the interrupt source will be stored here by getInterruptType.

    kIOInterruptTypeEdge will be returned for edge-trigggered sources.

    kIOInterruptTypeLevel will be returned for level-trigggered sources.

    Return Value

    An IOReturn code (kIOReturnNoInterrupt is returned if the source is not valid).

  • Finds the set of current published IOService objects matching a matching dictionary.

    Declaration

    C++

    static OSIterator * getMatchingServices( OSDictionary *matching );

    Parameters

    matching

    The matching dictionary describing the desired IOService objects.

    Return Value

    An instance of an iterator over a set of IOService objects. To be released by the caller.

    Discussion

    Provides a method of finding the current set of published IOService objects matching the supplied matching dictionary.

  • Returns an iterator over a provider's clients that currently have opened the provider.

    Declaration

    C++

    virtual OSIterator * getOpenClientIterator( void ) const;

    Return Value

    An iterator over the clients that have opened the provider, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, and the current entry in the iteration is locked with lockForArbitration, protecting it from state changes.

    Discussion

    For IOService objects that may have multiple clients, this method supplies an iterator over a provider's clients, locking each in turn with lockForArbitration and returning those that have opened the provider.

  • Returns an iterator over an client's providers that are currently opened by the client.

    Declaration

    C++

    virtual OSIterator * getOpenProviderIterator( void ) const;

    Return Value

    An iterator over the providers the client has open, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, and the current entry in the iteration is locked with lockForArbitration, protecting it from state changes.

    Discussion

    For those few IOService objects that obtain service from multiple providers, this method supplies an iterator over a client's providers, locking each in turn with lockForArbitration and returning those that have been opened by the client.

  • Returns a pointer to the platform expert instance for the computer.

    Declaration

    C++

    static IOPlatformExpert * getPlatform( void );

    Return Value

    A pointer to the IOPlatformExpert instance. It should not be released by the caller.

    Discussion

    This method provides an accessor to the platform expert instance for the computer.

  • Returns a pointer to the power management root domain instance for the computer.

    Declaration

    C++

    static class IOPMrootDomain * getPMRootDomain( void );

    Return Value

    A pointer to the power management root domain instance. It should not be released by the caller.

    Discussion

    This method provides an accessor to the power management root domain instance for the computer.

  • Returns a pointer to the system-wide power management work loop.

    Declaration

    C++

    virtual IOWorkLoop * getPMworkloop( void ) __attribute__((deprecated));

    Discussion

    Most drivers should create their own work loops to synchronize their code; drivers should not run arbitrary code on the power management work loop.

  • Determines a device's power state.

    Declaration

    C++

    UInt32 getPowerState( void );

    Return Value

    The current power state's index into the device's power state array.

    Discussion

    A device's "current power state" is updated at the end of each power state transition (e.g. transition from state 1 to state 0, or state 0 to state 2). This transition includes the time spent powering on or off any power plane children. Thus, if a child calls getPowerState on its power parent during system wake from sleep, the call will return the index to the device's off state rather than its on state.

  • Returns an IOService object's primary provider.

    Declaration

    C++

    virtual IOService * getProvider( void ) const;

    Return Value

    The first provider of the client, or zero if the IOService object is not attached into the I/O Registry. The provider is retained while the client is attached, and should not be released by the caller.

    Discussion

    This function called in an IOService client will return the provider to which it was first attached. Because the majority of IOService objects have only one provider, this is a useful simplification and also supports caching of the provider when the I/O Registry is unchanged.

  • Returns an iterator over an IOService object's providers.

    Declaration

    C++

    virtual OSIterator * getProviderIterator( void ) const;

    Return Value

    An iterator over the providers of the client, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, though they may no longer be attached during the iteration.

    Discussion

    For those few IOService objects that obtain service from multiple providers, this method supplies an iterator over a client's providers.

  • Allocates any needed resources for a published IOService object before clients attach.

    Declaration

    C++

    virtual IOReturn getResources( void );

    Return Value

    An IOReturn code; kIOReturnSuccess is necessary for the IOService object to be successfully used, otherwise the registration process for the object is halted.

    Discussion

    This method is called during the registration process for an IOService object if there are successful driver matches, before any clients attach. It allows for lazy allocation of resources to an IOService object when a matching driver is found.

  • Returns a pointer to the IOResources service.

    Declaration

    C++

    static IOService * getResourceService( void );

    Return Value

    A pointer to the IOResources instance. It should not be released by the caller.

    Discussion

    IOService maintains a resource service IOResources that allows objects to be published and found globally in the I/O Kit based on a name, using the standard IOService matching and notification calls.

  • Returns a pointer to the root of the service plane.

    Declaration

    C++

    static IOService * getServiceRoot( void );

    Return Value

    A pointer to the IOService instance at the root of the service plane. It should not be released by the caller.

    Discussion

    This method provides an accessor to the root of the service plane for the computer.

  • Accessor for IOService state bits, not normally needed or used outside IOService.

    Declaration

    C++

    virtual IOOptionBits getState( void ) const;

    Return Value

    State bits for the IOService, eg. kIOServiceInactiveState, kIOServiceRegisteredState.

  • Returns the current work loop or provider->getWorkLoop.

    Declaration

    C++

    virtual IOWorkLoop * getWorkLoop() const;

    Return Value

    A work loop, either the current work loop or it walks up the getProvider chain calling getWorkLoop. Eventually it will reach a valid work loop-based driver or the root of the I/O tree, where it will return a system-wide work loop. Returns 0 if it fails to find (or create) a work loop.

    Discussion

    This function returns a valid work loop that a client can use to add an IOCommandGate to. The intention is that an IOService client has data that needs to be protected but doesn't want to pay the cost of a dedicated thread. This data has to be accessed from a provider's call-out context as well. So to achieve both of these goals the client creates an IOCommandGate to lock access to his data but he registers it with the provider's work loop, i.e. the work loop which will make the completion call-outs. This avoids a potential deadlock because the work loop gate uses a recursive lock, which allows the same lock to be held multiple times by a single thread.

  • Controls the open / close behavior of an IOService object (overrideable by subclasses).

    Declaration

    C++

    virtual void handleClose( IOService *forClient, IOOptionBitsoptions );

    Parameters

    forClient

    Designates the client of the provider requesting the close.

    options

    Options for the close, may be interpreted by the implementor of handleOpen.

    Discussion

    IOService calls this method in its subclasses in response to the close method, so the subclass may implement the request. The default implementation provides single owner access to an IOService object via open. The object is locked via lockForArbitration before handleClose is called.

  • Controls the open / close behavior of an IOService object (overrideable by subclasses).

    Declaration

    C++

    virtual bool handleIsOpen( const IOService *forClient ) const;

    Parameters

    forClient

    If non-zero, isOpen returns the open state for that client. If zero is passed, isOpen returns the open state for all clients.

    Return Value

    true if the specific, or any, client has the IOService object open.

    Discussion

    IOService calls this method in its subclasses in response to the open method, so the subclass may implement the request. The default implementation provides single owner access to an IOService object via open. The object is locked via lockForArbitration before handleIsOpen is called.

  • Controls the open / close behavior of an IOService object (overrideable by subclasses).

    Declaration

    C++

    virtual bool handleOpen( IOService *forClient, IOOptionBits options, void *arg );

    Parameters

    forClient

    Designates the client of the provider requesting the open.

    options

    Options for the open, may be interpreted by the implementor of handleOpen.

    Return Value

    trueif the open was successful; false otherwise.

    Discussion

    IOService calls this method in its subclasses in response to the open method, so the subclass may implement the request. The default implementation provides single owner access to an IOService object via open. The object is locked via lockForArbitration before handleOpen is called.

  • Determines which power state a device is in, given the current power domain state.

    Declaration

    C++

    virtual unsigned long initialPowerStateForDomainState( IOPMPowerFlagsdomainState );

    Parameters

    domainState

    Flags that describe the character of "domain power"; they represent the outputPowerCharacter field of a state in the power domain's power state array.

    Return Value

    A state number.

    Discussion

    Power management calls this method once, when the driver is initializing power management. Most drivers do not need to implement this method, and can rely upon the default IOService implementation. The IOService implementation scans the power state array looking for the highest state whose inputPowerRequirement field exactly matches the value of the domainState parameter. If more intelligent determination is required, the power managed driver should implement the method and override the superclass's implementation.

  • Checks if the IOService object has been terminated, and is in the process of being destroyed.

    Declaration

    C++

    bool isInactive( void ) const;

    Return Value

    true if the IOService object has been terminated.

    Discussion

    When an IOService object is successfully terminated, it is immediately made inactive, which blocks further attach()es, matching or notifications occuring on the object. It remains inactive until the last client closes, and is then finalized and destroyed.

  • Determines whether a specific, or any, client has an IOService object open.

    Declaration

    C++

    virtual bool isOpen( const IOService *forClient = 0 ) const;

    Parameters

    forClient

    If non-zero, <codeisOpenreturns the open state for that client. If zero is passed, <codeisOpenreturns the open state for all clients.

    Return Value

    <codetrueif the specific, or any, client has the IOService object open.

    Discussion

    Returns the open state of an IOService object with respect to the specified client, or when it is open by any client.

  • Joins the driver into the power plane of the I/O Registry.

    Declaration

    C++

    virtual void joinPMtree( IOService *driver );

    Parameters

    driver

    The driver to be added to the power plane, usually this.

    Discussion

    A driver uses this method to call its nub when initializing (usually in its start routine after calling PMinit), to be attached into the power management hierarchy (i.e., the power plane). A driver usually calls this method on the driver for the device that provides it power (this is frequently the nub). Before this call returns, the caller will probably be called at setPowerParent and setAggressiveness and possibly at addPowerChild as it is added to the hierarchy. This method may be overridden by a nub subclass.

  • Locks an IOService object against changes in state or ownership.

    Declaration

    C++

    virtual bool lockForArbitration( bool isSuccessRequired = true );

    Parameters

    isSuccessRequired

    If a request for access to an IOService object should be denied if it is terminated, pass false, otherwise pass true.

    Discussion

    The registration, termination and open / close functions of IOService use lockForArbtration to single-thread access to an IOService object. lockForArbitration grants recursive access to the same thread.

  • Requests that a device become usable.

    Declaration

    C++

    IOReturn makeUsable( void );

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    This method is called when some client of a device (or the device's own driver) is asking for the device to become usable. Power management responds by telling the object upon which this method is called to change to its highest power state. makeUsable is implemented using changePowerStateToPriv. Subsequent requests for lower power, such as from changePowerStateToPriv, will pre-empt this request.

  • Maps a physical range of a device.

    Declaration

    C++

    virtual IOMemoryMap * mapDeviceMemoryWithIndex( unsigned intindex, IOOptionBits options = 0 );

    Parameters

    index

    An index into the array of ranges assigned to the device.

    Return Value

    An instance of IOMemoryMap, or zero if the index is beyond the count available. The mapping should be released only when access to it is no longer required.

    Discussion

    This method creates a mapping for the IODeviceMemory at the given index, with IODeviceMemory::map(options). The mapping is represented by the returned instance of IOMemoryMap, which should not be released until the mapping is no longer required.

  • Allows a registered IOService object to direct location matching.

    Declaration

    C++

    virtual IOService * matchLocation( IOService *client );

    Parameters

    client

    The IOService object at which matching is taking place.

    Return Value

    Returns the IOService instance to be used for location matching.

    Discussion

    By default, a location matching property will be applied to an IOService object's provider. This method allows that behavior to be overridden by families.

  • Allows a registered IOService object to implement family specific matching.

    Declaration

    C++

    virtual bool matchPropertyTable( OSDictionary *table, SInt32 *score );

    Parameters

    table

    The dictionary of properties to be matched against.

    score

    Pointer to the current driver's probe score, which is used to order multiple matching drivers in the same match category. It defaults to the value of the IOProbeScore property in the drivers property table, or kIODefaultProbeScore if none is specified.

    Return Value

    false if the family considers the matching dictionary does not match in properties it understands; true otherwise.

    Discussion

    All matching on an IOService object will call this method to allow a family writer to implement matching in addition to the generic methods provided by IOService. The implementer should examine the matching dictionary passed to see if it contains properties the family understands for matching, and use them to match with the IOService object if so. Note that since matching is also carried out by other parts of the I/O Kit, the matching dictionary may contain properties the family does not understand - these should not be considered matching failures.

  • Determines a driver's highest power state possible for a given power domain state.

    Declaration

    C++

    virtual unsigned long maxCapabilityForDomainState( IOPMPowerFlagsdomainState );

    Parameters

    domainState

    Flags that describe the character of "domain power"; they represent the outputPowerCharacter field of a state in the power domain's power state array.

    Return Value

    A state number.

    Discussion

    This happens when the power domain is changing state and power management needs to determine which state the device is capable of in the new domain state. Most drivers do not need to implement this method, and can rely upon the default IOService implementation. The IOService implementation scans the power state array looking for the highest state whose inputPowerRequirement field exactly matches the value of the domainState parameter. If more intelligent determination is required, the driver itself should implement the method and override the superclass's implementation.

  • Receives a generic message delivered from an attached provider.

    Declaration

    C++

    virtual IOReturn message( UInt32 type, IOService *provider, void *argument = 0 );

    Parameters

    type

    A type defined in IOMessage.h or defined by the provider family.

    provider

    The provider from which the message originates.

    argument

    An argument defined by the provider family, not used by IOService.

    Return Value

    An IOReturn code defined by the message type.

    Discussion

    A provider may deliver messages via the message method to its clients informing them of state changes, such as kIOMessageServiceIsTerminated or kIOMessageServiceIsSuspended. Certain messages are defined by the I/O Kit in IOMessage.h while others may be family dependent. This method is implemented in the client to receive messages.

  • Sends a generic message to an attached client.

    Declaration

    C++

    virtual IOReturn messageClient( UInt32 messageType, OSObject *client, void *messageArgument = 0, vm_size_t argSize = 0 );

    Parameters

    messageType

    A type defined in IOMessage.h or defined by the provider family.

    client

    A client of the IOService to send the message.

    messageArgument

    An argument defined by the provider family, not used by IOService.

    argSize

    Specifies the size of messageArgument, in bytes. If argSize is non-zero, messageArgument is treated as a pointer to argSize bytes of data. If argSize is 0 (the default), messageArgument is treated as an ordinal and passed by value.

    Return Value

    The return code from the client message call.

    Discussion

    A provider may deliver messages via the message method to its clients informing them of state changes, such as kIOMessageServiceIsTerminated or kIOMessageServiceIsSuspended. Certain messages are defined by the I/O Kit in IOMessage.h while others may be family dependent. This method may be called in the provider to send a message to the specified client, which may be useful for overrides.

  • Sends a generic message to all attached clients.

    Declaration

    C++

    virtual IOReturn messageClients( UInt32 type, void *argument = 0, vm_size_t argSize = 0 );

    Parameters

    type

    A type defined in IOMessage.h or defined by the provider family.

    argument

    An argument defined by the provider family, not used by IOService.

    argSize

    Specifies the size of argument, in bytes. If argSize is non-zero, argument is treated as a pointer to argSize bytes of data. If argSize is 0 (the default), argument is treated as an ordinal and passed by value.

    Return Value

    Any non-kIOReturnSuccess return codes returned by the clients, or kIOReturnSuccess if all return kIOReturnSuccess.

    Discussion

    A provider may deliver messages via the message method to its clients informing them of state changes, such as kIOMessageServiceIsTerminated or kIOMessageServiceIsSuspended. Certain messages are defined by the I/O Kit in IOMessage.h while others may be family dependent. This method may be called in the provider to send a message to all the attached clients, via the messageClient method.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match.

    Declaration

    C++

    static OSDictionary * nameMatching( const char *name, OSDictionary *table = 0 );

    Parameters

    name

    The service's name, as a const C string. Name matching is successful on IOService objects that respond successfully to the IORegistryEntry::compareName method.

    table

    If zero, nameMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    A very common matching criteria for IOService object is based on its name. nameMatching creates a matching dictionary that specifies any IOService object which responds successfully to the IORegistryEntry::compareName method. An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match.

    Declaration

    C++

    static OSDictionary * nameMatching( const OSString *name, OSDictionary *table = 0 );

    Parameters

    name

    The service's name, as an OSString (which includes OSSymbol). Name matching is successful on IOService objects that respond successfully to the IORegistryEntry::compareName method.

    table

    If zero, nameMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    A very common matching criteria for IOService object is based on its name. nameMatching creates a matching dictionary that specifies any IOService object which responds successfully to the IORegistryEntry::compareName method. An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.

  • Tells a power managed driver that the temperature in the thermal zone has changed.

    Declaration

    C++

    virtual IOReturn newTemperature( long currentTemp, IOService *whichZone ) __attribute__((deprecated));

    Discussion

    This call is unused by power management. It is not intended to be called or overridden.

  • Creates a connection for a non kernel client.

    Declaration

    C++

    virtual IOReturn newUserClient( task_towningTask, void *securityID, UInt32type, OSDictionary *handler, IOUserClient **properties );

    Parameters

    owningTask

    The Mach task of the client thread in the process of opening the user client. Note that in Mac OS X, each process is based on a Mach task and one or more Mach threads. For more information on the composition of a Mach task and its relationship with Mach threads, see Kernel Programming Guide.

    securityID

    A token representing the access level for the task.

    type

    A constant specifying the type of connection to be created, specified by the caller of IOServiceOpen and interpreted only by the family.

    handler

    An instance of an IOUserClient object to represent the connection, which will be released when the connection is closed, or zero if the connection was not opened.

    properties

    A dictionary of additional properties for the connection.

    Return Value

    A return code to be passed back to the caller of IOServiceOpen.

    Discussion

    A non kernel client may request a connection be opened via the IOServiceOpen library function, which will call this method in an IOService object. The rules and capabilities of user level clients are family dependent, and use the functions of the IOUserClient class for support. IOService's implementation returns kIOReturnUnsupported, so any family supporting user clients must implement this method.

  • Allows subclasses to customize idle power management behavior.

    Declaration

    C++

    virtual SInt32 nextIdleTimeout( AbsoluteTimecurrentTime, AbsoluteTimelastActivity, unsigned intpowerState);

    Parameters

    currentTime

    The current time

    lastActivity

    The time of last activity on this device

    powerState

    The device's current power state.

    Return Value

    Returns the next time the device should idle off (in seconds, relative to the current time).

    Discussion

    Returns the next time that the device should idle into its next lower power state. Subclasses may override for custom idle behavior.

    A power managed driver might override this method to provide a more sophisticated idle power off algorithm than the one defined by power management.

  • Requests active access to a provider.

    Declaration

    C++

    virtual bool open( IOService *forClient, IOOptionBits options = 0, void *arg = 0 );

    Parameters

    forClient

    Designates the client of the provider requesting the open.

    options

    Options for the open. The provider family may implement options for open; IOService defines only kIOServiceSeize to request the device be withdrawn from its current owner.

    Return Value

    true if the open was successful; false otherwise.

    Discussion

    IOService provides generic open and close semantics to track clients of a provider that have established an active datapath. The use of open and close, and rules regarding ownership are family defined, and defined by the handleOpen and handleClose methods in the provider. Some families will limit access to a provider based on its open state.

  • Declaration

    C++

    virtual void PM_Clamp_Timer_Expired( void ) __attribute__((deprecated));

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Declaration

    C++

    virtual void PM_idle_timer_expiration( void ) __attribute__((deprecated));

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Initializes power management for a driver.

    Declaration

    C++

    virtual void PMinit( void );

    Discussion

    PMinit allocates and initializes the power management instance variables, and it should be called before accessing those variables or calling the power management methods. This method should be called inside the driver's start routine and must be paired with a call to PMstop. Most calls to PMinit are followed by calls to joinPMtree and registerPowerDriver.

  • Stop power managing the driver.

    Declaration

    C++

    virtual void PMstop( void );

    Discussion

    Removes the driver from the power plane and stop its power management. This method is synchronous against any power management method invocations (e.g. setPowerState or setAggressiveness), so when this method returns it is guaranteed those power management methods will not be entered. Driver should not call any power management methods after this call. Calling PMstop cleans up for the three power management initialization calls: PMinit, joinPMtree, and registerPowerDriver.

  • Tells a driver when a power state change is complete.

    Declaration

    C++

    virtual void powerChangeDone( unsigned longstateNumber );

    Parameters

    stateNumber

    The number of the state in the state array that the device has switched from.

    Discussion

    Power management uses this method to inform a driver when a power change is completely done, when all interested parties have acknowledged the powerStateDidChangeTo call. The default implementation of this method is null; the method is meant to be overridden by subclassed power managed drivers. A driver should use this method to find out if a power change it initiated is complete.

  • Allows a driver to disable a power override.

    Declaration

    C++

    IOReturn powerOverrideOffPriv( void );

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    When a driver has enabled an override via powerOverrideOnPriv, it can disable it again by calling this method in its superclass. Disabling the override reverts to the default algorithm for determining a device's power state. The superclass will now keep the device at the highest state required by changePowerStateTo, changePowerStateToPriv, and its children. Turning off the override will initiate a power change if the driver's desired power state is different from the maximum of the power managed driver's desire and the children's desires.

  • Allows a driver to ignore its children's power management requests and only use changePowerStateToPriv to define its own power state.

    Declaration

    C++

    IOReturn powerOverrideOnPriv( void );

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    Power management normally keeps a device at the highest state required by its requests via changePowerStateTo, changePowerStateToPriv, and its children. However, a driver may ensure a lower power state than otherwise required by itself and its children using powerOverrideOnPriv. When the override is on, power management keeps the device's power state in the state specified by changePowerStateToPriv. Turning on the override will initiate a power change if the driver's changePowerStateToPriv desired power state is different from the maximum of the changePowerStateTo desired power state and the children's desires.

  • Informs interested parties that a device has changed to a different power state.

    Declaration

    C++

    virtual IOReturn powerStateDidChangeTo( IOPMPowerFlagscapabilities, unsigned longstateNumber, IOService *whatDevice );

    Parameters

    capabilities

    Flags that describe the capability of the device in the new power state (they come from the capabilityFlags field of the new state in the power state array).

    stateNumber

    The number of the state in the state array that the device is switching to.

    whatDevice

    A pointer to the driver that is changing. It can be used by a driver that is receiving power state change notifications for multiple devices to distinguish between them.

    Return Value

    The driver returns IOPMAckImplied if it has prepared for the power change when it returns. If it has started preparing but not finished, it should return a number of microseconds which is an upper limit of the time it will need to finish preparing. Then, when it has completed its preparations, it should call acknowledgePowerChange.

    Discussion

    Power management informs interested parties that a device has changed to a different power state. Interested parties are those that have registered for this notification via registerInterestedDriver. If you have called registerInterestedDriver on a power managed driver, you must implemnt powerStateWillChangeTo and powerStateDidChangeTo to receive the notifications. powerStateDidChangeTo is called in a clean and separate thread context. powerStateWillChangeTo is called before a power state transition takes place; powerStateDidChangeTo is called after the transition has completed.

  • Determines what power state the device would be in for a given power domain state.

    Declaration

    C++

    virtual unsigned long powerStateForDomainState( IOPMPowerFlagsdomainState );

    Parameters

    domainState

    Flags that describe the character of "domain power"; they represent the outputPowerCharacter field of a state in the power domain's power state array.

    Return Value

    A state number.

    Discussion

    Power management calls a driver with this method to find out what power state the device would be in for a given power domain state. This happens when the power domain is changing state and power management needs to determine the effect of the change. Most drivers do not need to implement this method, and can rely upon the default IOService implementation. The IOService implementation scans the power state array looking for the highest state whose inputPowerRequirement field exactly matches the value of the domainState parameter. If more intelligent determination is required, the power managed driver should implement the method and override the superclass's implementation.

  • Informs interested parties that a device is about to change its power state.

    Declaration

    C++

    virtual IOReturn powerStateWillChangeTo( IOPMPowerFlagscapabilities, unsigned longstateNumber, IOService *whatDevice );

    Parameters

    capabilities

    Flags that describe the capability of the device in the new power state (they come from the capabilityFlags field of the new state in the power state array).

    stateNumber

    The number of the state in the state array that the device is switching to.

    whatDevice

    A pointer to the driver that is changing. It can be used by a driver that is receiving power state change notifications for multiple devices to distinguish between them.

    Return Value

    The driver returns IOPMAckImplied if it has prepared for the power change when it returns. If it has started preparing but not finished, it should return a number of microseconds which is an upper limit of the time it will need to finish preparing. Then, when it has completed its preparations, it should call acknowledgePowerChange.

    Discussion

    Power management informs interested parties that a device is about to change to a different power state. Interested parties are those that have registered for this notification via registerInterestedDriver. If you have called registerInterestedDriver on a power managed driver, you must implement powerStateWillChangeTo and powerStateDidChangeTo to receive the notifications. powerStateWillChangeTo is called in a clean and separate thread context. powerStateWillChangeTo is called before a power state transition takes place; powerStateDidChangeTo is called after the transition has completed.

  • During an IOService object's instantiation, probes a matched service to see if it can be used.

    Declaration

    C++

    virtual IOService * probe( IOService *provider, SInt32 *score );

    Parameters

    provider

    The registered IOService object that matches a driver personality's matching dictionary.

    score

    Pointer to the current driver's probe score, which is used to order multiple matching drivers in the same match category. It defaults to the value of the IOProbeScore property in the drivers property table, or kIODefaultProbeScore if none is specified. The probe method may alter the score to affect start order.

    Return Value

    An IOService instance or zero when the probe is unsuccessful. In almost all cases the value of this is returned on success. If another IOService object is returned, the probed instance is detached and freed, and the returned instance is used in its stead for start.

    Discussion

    The registration process for an IOService object (the provider) includes instantiating possible driver clients. The probe method is called in the client instance to check the matched service can be used before the driver is considered to be started. Since matching screens many possible providers, in many cases the probe method can be left unimplemented by IOService subclasses. The client is already attached to the provider when probe is called.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService phandle match.

    Declaration

    C++

    static OSDictionary * propertyMatching( const OSSymbol *key, const OSObject *value, OSDictionary *table = 0 );

    Parameters

    key

    The service's phandle, as a const UInt32. PHandle matching is successful on IOService objects that respond successfully to the IORegistryEntry method compareName.

    value

    The service's phandle, as a const UInt32. PHandle matching is successful on IOService's which respond successfully to the IORegistryEntry method compareName.

    table

    If zero, nameMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    TODO A very common matching criteria for IOService is based on its name. nameMatching will create a matching dictionary that specifies any IOService which respond successfully to the IORegistryEntry method compareName. An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.

  • Uses the resource service to publish a property.

    Declaration

    C++

    static void publishResource( const char *key, OSObject *value = 0 );

    Parameters

    key

    A C string key that globally identifies the object.

    The

    object to be published.

    Discussion

    The resource service uses IOService object's matching and notification to allow objects to be published and found by any I/O Kit client by a global name. publishResource makes an object available to anyone waiting for it or looking for it in the future.

  • Uses the resource service to publish a property.

    Declaration

    C++

    static void publishResource( const OSSymbol *key, OSObject *value = 0 );

    Parameters

    key

    An OSSymbol key that globally identifies the object.

    The

    object to be published.

    Discussion

    The resource service uses IOService's matching and notification to allow objects to be published and found by any I/O Kit client by a global name. publishResource makes an object available to anyone waiting for it or looking for it in the future.

  • Allows an IOService object to register interest in the changing power state of a power-managed IOService object.

    Declaration

    C++

    IOPMPowerFlags registerInterestedDriver( IOService *theDriver );

    Parameters

    theDriver

    The driver of interest adds this pointer to the list of interested drivers. It informs drivers on this list before and after the power change.

    Return Value

    Flags describing the capability of the device in its current power state. If the current power state is not yet defined, zero is returned (this is the case when the driver is not yet in the power domain hierarchy or hasn't fully registered with power management yet).

    Discussion

    Call registerInterestedDriver on the IOService object you are interested in receiving power state messages from, and pass a pointer to the interested driver (this) as an argument. The interested driver is retained until the power interest is removed by calling deRegisterInterestedDriver. The interested driver should override powerStateWillChangeTo and powerStateDidChangeTo to receive these power change messages. Interested drivers must acknowledge power changes in powerStateWillChangeTo or powerStateDidChangeTo, either via return value or later calls to acknowledgePowerChange.

  • Registers a C function interrupt handler for a device supplying interrupts.

    Declaration

    C++

    virtual IOReturn registerInterrupt( int source, OSObject *target, IOInterruptAction handler, void *refCon = 0);

    Parameters

    source

    The index of the interrupt source in the device.

    target

    An object instance to be passed to the interrupt handler.

    handler

    The C function to be called at primary interrupt time when the interrupt occurs. The handler should process the interrupt by clearing the interrupt, or by disabling the source.

    refCon

    A reference constant for the handler's use.

    Return Value

    An IOReturn code.

    kIOReturnNoInterrupt is returned if the source is not valid; kIOReturnNoResources is returned if the interrupt already has an installed handler.

    Discussion

    This method installs a C function interrupt handler to be called at primary interrupt time for a device's interrupt. Only one handler may be installed per interrupt source. IOInterruptEventSource provides a work loop based abstraction for interrupt delivery that may be more appropriate for work loop based drivers.

  • Registers a set of power states that the driver supports.

    Declaration

    C++

    virtual IOReturn registerPowerDriver( IOService *controllingDriver, IOPMPowerState *powerStates, unsigned longnumberOfStates );

    Parameters

    controllingDriver

    A pointer to the calling driver, usually this.

    powerStates

    A driver-defined array of power states that the driver and device support. Power states are defined in pwr_mgt/IOPMpowerState.h.

    numberOfStates

    The number of power states in the array.

    Return Value

    IOPMNoErr. All errors are logged via kprintf.

    Discussion

    A driver defines its array of supported power states with power management in its power management initialization (its start routine). If successful, power management will call the driver to instruct it to change its power state through setPowerState. Most drivers do not need to override registerPowerDriver. A nub may override registerPowerDriver if it needs to arrange its children in the power plane differently than the default placement, but this is uncommon.

  • Starts the registration process for a newly discovered IOService object.

    Declaration

    C++

    virtual void registerService( IOOptionBits options = 0 );

    Parameters

    options

    The default zero options mask is recommended and should be used in most cases. The registration process is usually asynchronous, with possible driver probing and notification occurring some time later. kIOServiceSynchronous may be passed to carry out the matching and notification process for currently registered clients before returning to the caller.

    Discussion

    This function allows an IOService subclass to be published and made available to possible clients, by starting the registration process and delivering notifications to registered clients. The object should be completely setup and ready to field requests from clients before registerService is called.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a IORegistryEntryID match.

    Declaration

    C++

    static OSDictionary * registryEntryIDMatching( uint64_t entryID, OSDictionary *table = 0 );

    Parameters

    name

    The service's ID. Matching is successful on the IOService object that return that ID from the IORegistryEntry::getRegistryEntryID() method.

    table

    If zero, registryEntryIDMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    registryEntryIDMatching creates a matching dictionary that specifies the IOService object with the assigned registry entry ID (returned by IORegistryEntry::getRegistryEntryID()). An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.

  • Informs a power managed driver that one of its power plane childen is disappearing.

    Declaration

    C++

    virtual IOReturn removePowerChild( IOPowerConnection *theChild );

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Tells a driver to adjust its power state.

    Declaration

    C++

    virtual IOReturn requestPowerDomainState( IOPMPowerFlags desiredState, IOPowerConnection *whichChild, unsigned long specificationFlags );

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Requests that hardware be re-scanned for devices.

    Declaration

    C++

    virtual IOReturn requestProbe( IOOptionBitsoptions );

    Parameters

    options

    Family defined options, not interpreted by IOService.

    Return Value

    An IOReturn code.

    Discussion

    For bus families that do not usually detect device addition or removal, this method represents an external request (eg. from a utility application) to rescan and publish or remove found devices.

  • Passes a termination up the stack.

    Declaration

    C++

    virtual bool requestTerminate( IOService *provider, IOOptionBitsoptions );

    Parameters

    provider

    The terminated provider of this object.

    options

    Options originally passed to terminate, plus kIOServiceRecursing.

    Return Value

    true if this object should be terminated now that its provider has been.

    Discussion

    When an IOService is made inactive the default behavior is to also make any of its clients that have it as their only provider also inactive, in this way recursing the termination up the driver stack. This method allows an IOService object to override this behavior. Returning true from this method when passed a just terminated provider will cause the client to also be terminated.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match.

    Declaration

    C++

    static OSDictionary * resourceMatching( const char *name, OSDictionary *table = 0 );

    Parameters

    name

    The resource name, as a const C string. Resource matching is successful when an object by that name has been published with the publishResource method.

    table

    If zero, resourceMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    IOService maintains a resource service IOResources that allows objects to be published and found globally in the I/O Kit based on a name, using the standard IOService matching and notification calls.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match.

    Declaration

    C++

    static OSDictionary * resourceMatching( const OSString *name, OSDictionary *table = 0 );

    Parameters

    name

    The resource name, as an OSString (which includes OSSymbol). Resource matching is successful when an object by that name has been published with the publishResource method.

    table

    If zero, resourceMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    IOService maintains a resource service IOResources that allows objects to be published and found globally in the I/O Kit based on a name, using the standard IOService matching and notification calls.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match.

    Declaration

    C++

    static OSDictionary * serviceMatching( const char *className, OSDictionary *table = 0 );

    Parameters

    className

    The class name, as a const C string. Class matching is successful on IOService objects of this class or any subclass.

    table

    If zero, serviceMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    A very common matching criteria for IOService object is based on its class. serviceMatching creates a matching dictionary that specifies any IOService object of a class, or its subclasses. The class is specified by name, and an existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.

  • Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match.

    Declaration

    C++

    static OSDictionary * serviceMatching( const OSString *className, OSDictionary *table = 0 );

    Parameters

    className

    The class name, as an OSString (which includes OSSymbol). Class matching is successful on IOService objects of this class or any subclass.

    table

    If zero, serviceMatching creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.

    Return Value

    The matching dictionary created, or passed in, is returned on success, or zero on failure.

    Discussion

    A very common matching criteria for IOService object is based on its class. serviceMatching creates a matching dictionary that specifies any IOService of a class, or its subclasses. The class is specified by name, and an existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.

  • Broadcasts an aggressiveness factor from the parent of a driver to the driver.

    Declaration

    C++

    virtual IOReturn setAggressiveness( unsigned longtype, unsigned longnewLevel );

    Parameters

    type

    The aggressiveness factor type, such as kPMMinutesToDim, kPMMinutesToSpinDown, kPMMinutesToSleep, and kPMPowerSource. (Aggressiveness factors are defined in pwr_mgt/IOPM.h.)

    newLevel

    The aggressiveness factor's new value.

    Return Value

    IOPMNoErr.

    Discussion

    Implement setAggressiveness to receive a notification when an "aggressiveness Aggressiveness factors are a loose set of power management variables that contain values for system sleep timeout, display sleep timeout, whether the system is on battery or AC, and other power management features. There are several aggressiveness factors that can be broadcast and a driver may take action on whichever factors apply to it. A driver that has joined the power plane via joinPMtree will receive setAgressiveness calls when aggressiveness factors change. A driver may override this call if it needs to do something with the new factor (such as change its idle timeout). If overridden, the driver must call its superclass's setAgressiveness method in its own setAgressiveness implementation. Most drivers do not need to implement setAgressiveness.

  • Sets the array of IODeviceMemory objects representing a device's memory mapped ranges.

    Declaration

    C++

    virtual void setDeviceMemory( OSArray *array );

    Parameters

    array

    An OSArray of IODeviceMemory objects, or zero if none are available. The array will be retained by the object.

    Discussion

    This method sets an array of IODeviceMemory objects representing the physical memory ranges allocated to a memory mapped device.

  • Sets or changes the idle timer period.

    Declaration

    C++

    virtual IOReturn setIdleTimerPeriod( unsignedperiod );

    Parameters

    period

    The desired idle timer period in seconds.

    Return Value

    kIOReturnSuccess upon success; an I/O Kit error code otherwise.

    Discussion

    A driver using the idleness determination provided by IOService calls its superclass with this method to set or change the idle timer period. See activityTickle for a description of this type of idleness determination.

  • This call is handled internally by power management. It is not intended to be overridden or called by drivers.

    Declaration

    C++

    virtual IOReturn setPowerParent( IOPowerConnection *parent, bool stateKnown, IOPMPowerFlags currentState ) __attribute__((deprecated));

  • Requests a power managed driver to change the power state of its device.

    Declaration

    C++

    virtual IOReturn setPowerState( unsigned longpowerStateOrdinal, IOService *whatDevice );

    Parameters

    powerStateOrdinal

    The number in the power state array of the state the driver is being instructed to switch to.

    whatDevice

    A pointer to the power management object which registered to manage power for this device. In most cases, whatDevice will be equal to your driver's own this pointer.

    Return Value

    The driver must return IOPMAckImplied if it has complied with the request when it returns. Otherwise if it has started the process of changing power state but not finished it, the driver should return a number of microseconds which is an upper limit of the time it will need to finish. Then, when it has completed the power switch, it should call acknowledgeSetPowerState.

    Discussion

    A power managed driver must override setPowerState to take part in system power management. After a driver is registered with power management, the system uses setPowerState to power the device off and on for system sleep and wake. Calls to PMinit and registerPowerDriver enable power management to change a device's power state using setPowerState. setPowerState is called in a clean and separate thread context.

  • During an IOService object's instantiation, starts the IOService object that has been selected to run on the provider.

    Declaration

    C++

    virtual bool start( IOService *provider );

    Return Value

    true if the start was successful; false otherwise (which will cause the instance to be detached and usually freed).

    Discussion

    The start method of an IOService instance is called by its provider when it has been selected (due to its probe score and match category) as the winning client. The client is already attached to the provider when start is called.

    Implementations of start must call start on their superclass at an appropriate point. If an implementation of start has already called super::start but subsequently determines that it will fail, it must call super::stop to balance the prior call to super::start and prevent reference leaks.

  • Declaration

    C++

    void start_PM_idle_timer( void );

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • During an IOService termination, the stop method is called in its clients before they are detached & it is destroyed.

    Declaration

    C++

    virtual void stop( IOService *provider );

    Discussion

    The termination process for an IOService (the provider) will call stop in each of its clients, after they have closed the provider if they had it open, or immediately on termination.

  • Supplies a programmer-friendly string from an IOReturn code.

    Declaration

    C++

    virtual const char * stringFromReturn( IOReturnrtn );

    Parameters

    rtn

    The IOReturn code.

    Return Value

    A pointer to a constant string, or zero if the return code is unknown.

    Discussion

    Strings are available for the standard return codes in IOReturn.h in IOService, while subclasses may implement this method to interpret family dependent return codes.

  • Tells every driver in the power plane that the system is waking up.

    Declaration

    C++

    virtual IOReturn systemWake( void ) __attribute__((deprecated));

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

  • Notifies members of the power plane of system shutdown and restart.

    Declaration

    C++

    virtual void systemWillShutdown( IOOptionBitsspecifier );

    Parameters

    specifier

    kIOMessageSystemWillPowerOff or kIOMessageSystemWillRestart.

    Discussion

    This function is called for all members of the power plane in leaf-to-root order. If a subclass needs to wait for a pending I/O, then the call to systemWillShutdown should be postponed until the I/O completes.

    Any power managed driver (which has called joinPMtree to join the power plane) interested in taking action at system shutdown or restart should override this method.

  • Alerts a driver to a critical temperature in some thermal zone.

    Declaration

    C++

    virtual IOReturn temperatureCriticalForZone( IOService *whichZone ) __attribute__((deprecated));

    Discussion

    This call is unused by power management. It is not intended to be called or overridden.

  • A driver calls this method to hold itself in the highest power state until it has children.

    Declaration

    C++

    IOReturn temporaryPowerClampOn( void );

    Return Value

    A return code that can be ignored by the caller.

    Discussion

    Use temporaryPowerClampOn to hold your driver in its highest power state while waiting for child devices to attach. After children have attached, the clamp is released and the device's power state is controlled by the children's requirements.

  • Makes an IOService object inactive and begins its destruction.

    Declaration

    C++

    virtual bool terminate( IOOptionBits options = 0 );

    Parameters

    options

    In most cases no options are needed. kIOServiceSynchronous may be passed to cause terminate to not return until the service is finalized.

    Discussion

    Registering an IOService object informs possible clients of its existance and instantiates drivers that may be used with it; terminate involves the opposite process of informing clients that an IOService object is no longer able to be used and will be destroyed. By default, if any client has the service open, terminate fails. If the kIOServiceRequired flag is passed however, terminate will be successful though further progress in the destruction of the IOService object will not proceed until the last client has closed it. The service will be made inactive immediately upon successful termination, and all its clients will be notified via their message method with a message of type kIOMessageServiceIsTerminated. Both these actions take place on the caller's thread. After the IOService object is made inactive, further matching or attach calls will fail on it. Each client has its stop method called upon their close of an inactive IOService object , or on its termination if they do not have it open. After stop, detach is called in each client. When all clients have been detached, the finalize method is called in the inactive service. The termination process is inherently asynchronous because it will be deferred until all clients have chosen to close.

  • Passes a termination up the stack.

    Declaration

    C++

    virtual bool terminateClient( IOService *client, IOOptionBitsoptions );

    Parameters

    client

    The client of the terminated provider.

    options

    Options originally passed to terminate, plus kIOServiceRecursing.

    Return Value

    result of the terminate request on the client.

    Discussion

    When an IOService object is made inactive the default behavior is to also make any of its clients that have it as their only provider inactive, in this way recursing the termination up the driver stack. This method allows a terminated IOService object to override this behavior. Note the client may also override this behavior by overriding its terminate method.

  • Unlocks an IOService obkect after a successful lockForArbitration.

    Declaration

    C++

    virtual void unlockForArbitration( void );

    Discussion

    A thread granted exclusive access to an IOService object should release it with unlockForArbitration.

  • Removes a C function interrupt handler for a device supplying hardware interrupts.

    Declaration

    C++

    virtual IOReturn unregisterInterrupt( intsource);

    Parameters

    source

    The index of the interrupt source in the device.

    Return Value

    An IOReturn code (kIOReturnNoInterrupt is returned if the source is not valid).

    Discussion

    This method removes a C function interrupt handler previously installed with registerInterrupt.

  • request current data for the specified channels

    Declaration

    C++

    virtual IOReturn updateReport( IOReportChannelList *channels, IOReportUpdateActionaction, void *result, void *destination);

    Parameters

    channels

    - channels to be updated

    action

    - type/style of update

    result

    - returned details about what was updated

    destination

    - destination for this update (action-specific)

  • Waits for a matching to service to be published.

    Declaration

    C++

    static IOService * waitForMatchingService( OSDictionary *matching, uint64_t timeout = timeout);

    Parameters

    matching

    The matching dictionary describing the desired IOService object. (Does not consume a reference of the matching dictionary - differs from waitForService() which does consume a reference on the matching dictionary.)

    timeout

    The maximum time to wait in nanoseconds. Default is to wait forever.

    Return Value

    A published IOService object matching the supplied dictionary. waitForMatchingService returns a reference to the IOService which should be released by the caller. (Differs from waitForService() which does not retain the returned object.)

    Discussion

    Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched.

  • Deprecated use waitForMatchingService(). Waits for a matching to service to be published.

    Declaration

    C++

    static IOService * waitForService( OSDictionary *matching, mach_timespec_t *timeout = 0);

    Parameters

    matching

    The matching dictionary describing the desired IOService object. waitForService consumes one reference of the matching dictionary.

    timeout

    The maximum time to wait.

    Return Value

    A published IOService object matching the supplied dictionary.

    Discussion

    Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched.

  • Waits for an IOService object's busyState to be zero.

    Declaration

    C++

    IOReturn waitQuiet( uint64_t timeout = timeout);

    Parameters

    timeout

    The maximum time to wait in nanoseconds. Default is to wait forever.

    Return Value

    Returns an error code if Mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess.

    Discussion

    Blocks the caller until an IOService object is non busy.

  • Passes a termination up the stack.

    Declaration

    C++

    virtual bool willTerminate( IOService *provider, IOOptionBitsoptions );

    Parameters

    provider

    The terminated provider of this object.

    options

    Options originally passed to terminate.

    Return Value

    true.

    Discussion

    Notification that a provider has been terminated, sent before recursing up the stack, in root-to-leaf order.

  • Informs power management which IOService object is the power plane root.

    Declaration

    C++

    virtual IOReturn youAreRoot( void ) __attribute__((deprecated));

    Discussion

    This call is handled internally by power management. It is not intended to be overridden or called by drivers.

Data Types

  • Declaration

    C++

    struct ExpansionData { };

    Discussion

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

Instance Variables

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * reserved;