Class

IOService

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

Overview

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.

Symbols

Miscellaneous

- acknowledgePowerChange

Acknowledges an in-progress power state change.

- acknowledgeSetPowerState

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

- activityTickle

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.

- addLocation

Adds a location matching property to an existing dictionary.

- addMatchingNotification

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

- addNotification

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

- addPowerChild

Informs a driver that it has a new child.

- adjustBusy

Adjusts the busyState of an IOService object.

- attach

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

- callPlatformFunction

Calls the platform function with the given name.

- causeInterrupt

Causes a device interrupt to occur.

- changePowerStateTo

Sets a driver's power state.

- changePowerStateToPriv

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

- clampPowerOn

Deprecated. Do not use.

- close

Releases active access to a provider.

- compareProperties

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

- compareProperty(OSDictionary *, const char *)

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

- compareProperty(OSDictionary *, const OSString *)

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

- configureReport

configure IOReporting channels

- copyMatchingService

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

- currentCapability

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

- currentPowerConsumption

Finds out the current power consumption of a device.

- deRegisterInterestedDriver

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

- detach

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

- didTerminate

Passes a termination up the stack.

- didYouWakeSystem

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

- disableInterrupt

Synchronously disables a device interrupt.

- enableInterrupt

Enables a device interrupt.

- errnoFromReturn

Translates an IOReturn code to a BSD errno.

- finalize

Finalizes the destruction of an IOService object.

- free

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

- getAggressiveness

Returns the current aggressiveness value for the given type.

- getBusyState

Returns the busyState of an IOService object.

- getClient

Returns an IOService object's primary client.

- getClientIterator

Returns an iterator over an IOService object's clients.

- getDeviceMemory

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

- getDeviceMemoryCount

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

- getDeviceMemoryWithIndex

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

- getInterruptType

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

- getMatchingServices

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

- getOpenClientIterator

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

- getOpenProviderIterator

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

- getPlatform

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

- getPMRootDomain

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

- getPMworkloop

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

- getPowerState

Determines a device's power state.

- getProvider

Returns an IOService object's primary provider.

- getProviderIterator

Returns an iterator over an IOService object's providers.

- getResources

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

- getResourceService

Returns a pointer to the IOResources service.

- getServiceRoot

Returns a pointer to the root of the service plane.

- getState

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

- getWorkLoop

Returns the current work loop or provider->getWorkLoop.

- handleClose

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

- handleIsOpen

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

- handleOpen

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

- initialPowerStateForDomainState

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

- isInactive

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

- isOpen

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

- joinPMtree

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

- lockForArbitration

Locks an IOService object against changes in state or ownership.

- makeUsable

Requests that a device become usable.

- mapDeviceMemoryWithIndex

Maps a physical range of a device.

- matchLocation

Allows a registered IOService object to direct location matching.

- matchPropertyTable

Allows a registered IOService object to implement family specific matching.

- maxCapabilityForDomainState

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

- message

Receives a generic message delivered from an attached provider.

- messageClient

Sends a generic message to an attached client.

- messageClients

Sends a generic message to all attached clients.

- nameMatching(const char *, OSDictionary *)

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

- nameMatching(const OSString *, OSDictionary *)

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

- newTemperature

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

- newUserClient

Creates a connection for a non kernel client.

- nextIdleTimeout

Allows subclasses to customize idle power management behavior.

- open

Requests active access to a provider.

- PMinit

Initializes power management for a driver.

- PMstop

Stop power managing the driver.

- powerChangeDone

Tells a driver when a power state change is complete.

- powerOverrideOffPriv

Allows a driver to disable a power override.

- powerOverrideOnPriv

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

- powerStateDidChangeTo

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

- powerStateForDomainState

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

- powerStateWillChangeTo

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

- probe

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

- propertyMatching

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

- publishResource(const char *, OSObject *)

Uses the resource service to publish a property.

- publishResource(const OSSymbol *, OSObject *)

Uses the resource service to publish a property.

- registerInterestedDriver

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

- registerInterrupt

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

- registerPowerDriver

Registers a set of power states that the driver supports.

- registerService

Starts the registration process for a newly discovered IOService object.

- registryEntryIDMatching

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

- removePowerChild

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

- requestPowerDomainState

Tells a driver to adjust its power state.

- requestProbe

Requests that hardware be re-scanned for devices.

- requestTerminate

Passes a termination up the stack.

- resourceMatching(const char *, OSDictionary *)

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

- resourceMatching(const OSString *, OSDictionary *)

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

- serviceMatching(const char *, OSDictionary *)

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

- serviceMatching(const OSString *, OSDictionary *)

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

- setAggressiveness

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

- setDeviceMemory

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

- setIdleTimerPeriod

Sets or changes the idle timer period.

- setPowerParent

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

- setPowerState

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

- start

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

- stop

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

- stringFromReturn

Supplies a programmer-friendly string from an IOReturn code.

- systemWake

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

- systemWillShutdown

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

- temperatureCriticalForZone

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

- temporaryPowerClampOn

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

- terminate

Makes an IOService object inactive and begins its destruction.

- terminateClient

Passes a termination up the stack.

- unlockForArbitration

Unlocks an IOService obkect after a successful lockForArbitration.

- unregisterInterrupt

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

- updateReport

request current data for the specified channels

- waitForMatchingService

Waits for a matching to service to be published.

- waitForService

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

- waitQuiet

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

- willTerminate

Passes a termination up the stack.

- youAreRoot

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

DataTypes

Instance Variables

Instance Methods

- PMinit- PMstop- acknowledgeNotification- acknowledgePowerChange- acknowledgeSetPowerState- activityTickle- addInterruptStatistics- addNeededResource- addPowerChild- adjustBusy- allowPowerChange- applyToClients- applyToInterested- applyToProviders- askChangeDown- attach- callPlatformFunction- cancelPowerChange- causeInterrupt- changePowerStateTo- changePowerStateToPriv- checkResource- checkResources- clampPowerOn- close- command_received- compareProperties- compareProperty- configureReport- copyClientWithCategory- currentCapability- currentPowerConsumption- deRegisterInterestedDriver- deliverNotification- detach- didTerminate- disableInterrupt- doServiceMatch- doServiceTerminate- enableInterrupt- errnoFromReturn- finalize- free- getAggressiveness- getBusyState- getClient- getClientIterator- getDeviceMemory- getDeviceMemoryCount- getDeviceMemoryWithIndex- getInterruptType- getMetaClass- getOpenClientIterator- getOpenProviderIterator
- getPMworkloopDeprecated
- getPowerState- getProvider- getProviderIterator- getResources- getState- getWorkLoop- handleClose- handleIsOpen- handleOpen- init- initialPowerStateForDomainState- invokeNotifer- isInactive- isOpen- joinPMtree- lockForArbitration- lookupInterrupt- makeUsable- mapDeviceMemoryWithIndex- matchInternal- matchLocation- matchPassive- matchPropertyTable- maxCapabilityForDomainState- message- messageClient- messageClients- newUserClient- nextIdleTimeout- open- passiveMatch- powerChangeDone- powerOverrideOffPriv- powerOverrideOnPriv- powerStateDidChangeTo- powerStateForDomainState- powerStateWillChangeTo- probe- probeCandidates- registerInterest- registerInterestedDriver- registerInterrupt- registerPowerDriver- registerService- removeInterruptStatistics- removePowerChild- requestPowerDomainState- requestProbe- requestTerminate- requireMaxBusStall- requireMaxInterruptDelay- resolveInterrupt- scheduleStop- scheduleTerminatePhase2- serializeProperties- setAggressiveness- setDeviceMemory- setIdleTimerPeriod- setPowerState- start- startCandidate- startMatching- start_PM_idle_timer- stop- stringFromReturn
- systemWakeDeprecated
- systemWillShutdown- tellChangeDown- tellChangeUp- tellNoChangeDown- temporaryPowerClampOn- terminate- terminateClient- terminatePhase1- unlockForArbitration- unregisterAllInterest- unregisterInterrupt- updateReport- waitForState
- waitQuietDeprecated
- willTerminate
- youAreRootDeprecated