IOService



Member Functions

PMinit

public:

void PMinit(void );

A power managment policy-maker for a device calls itself here to initialize its power management. PMinit allocates and initializes the power management instance variables, and it should be called before any access to those variables or the power management methods.


PMstop

public:

void PMstop( void );

A power managment policy-maker for a device calls itself here when it resigns its responsibilities as policy-maker. This typically happens when it is handing off the responsibility to another policy-maker, or when the device is removed from the system. The power managment variables don't exist after this call, and the power managment methods in the caller shouldn't be accessed.


acknowledgePowerChange

public:

IOReturn acknowledgePowerChange( IOService * whichDriver );

When a device is changing power state, its policy-maker informs interested parties before and after the change. Interested parties are those which have registered as interested drivers and also children of the policy-maker in the case that it is a power domain. When an object is so informed, it can return an indication that it is prepared for the change, or it can return an indication that it needs some time to prepare. In this case it will call this method in the policy-maker when it has prepared.

Parameters

NameDescription
theDriverThis points to the calling driver. The policy-maker uses it to know if all interested parties have acknowledged the power state change.
Result: IOPMNoErr is returned.

acknowledgeSetPowerState

public:

IOReturn acknowledgeSetPowerState( void );

When a policy-maker instructs its controlling driver to switch the state of the device, the driver can return an indication that the change is complete, or it can return an indication that it needs some time to make the change. In this case it will call this method in the policy-maker when it has made the power state change.

Result: IOPMNoErr is returned.

activityTickle

public:

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

A principal function of a policy-maker is deciding when the device is idle and can be powered down. To do this it needs to know when the device is being used. In some cases it is in the data path to the device so it knows when it is being used. In others it is not and must be told. The activityTickle method is provided for objects in the system to tell a policy-maker that its device is being used.

If the policy-maker is managing the idleness determination totally on its own, the paramter should be kIOPMSubclassPolicy, and the policy-maker should intercept the activityTickle call, because the superclass will do nothing with it.

The IOService superclass can manage idleness determination, too, with the simple mechanism of an idle timer and this activityTickle call. To start this up, the policy- maker calls its superclass at 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 call to activityTickle will cause the device to be switched to a higher state required for the activity.

activityTickle in the IOService superclass is meant to be called by sub-classed policy-makers, because only they understand the paramters. They may implement an activityTickle for their clients and then call this activityTickle in the superclass.

Parameters

NameDescription
typeactivityTickle with parameter kIOPMSubclassPolicy is not handled in IOService and should be intercepted by the subclass policy-maker. activityTickle with parameter kIOPMSuperclassPolicy1 causes an activity flag to be set, and the device state checked. If the device has been powered down, it is powered up again.
stateNumberWhen the type parameter is kIOPMSuperclassPolicy1, the 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 which can handle some accesses in lower power states than others; the device is powered up only as far as it needs to be for the activity.
Result: When the type parameter is kIOPMSuperclassPolicy1, the superclass returns true if the device is currently in the state specified by stateNumber. If it is in a lower state and must be brought up, it returns false. In this case the superclass will cause the device to be brought up.

addChild

public:

virtual IOReturn addChild( IOService * theChild );

The Platform Expert or some other IOService calls a power domain policy-maker here to introduce it to a child of it, a member of the domain.

Parameters

NameDescription
theChildThis is a pointer to the child IOService, which is another power domain policy-maker or a device policy-maker.

addLocation

Abstract: Add a location matching property to an existing dictionary.
public:

static OSDictionary * addLocation( OSDictionary * table );

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

Parameters

NameDescription
tableThe matching properties are added to the specified dictionary, which must be non-zero.
Result: The location matching dictionary created is returned on success, or zero on failure.

addNotification

Abstract: Add a persistant notification handler to be notified of IOService events.
public:

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

IOService will deliver notifications of changes in state of an IOService to registered clients. The type of notification is specified by a symbol, for example gIOMatchedNotification or gIOTerminatedNotification, and notifications will only include IOService's 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's 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 will consume a retain count on the matching dictionary when the notification is removed.

Parameters

NameDescription
typeAn OSSymbol identifying the type of notification and IOService state:
gIOPublishNotification Delivered when an IOService is registered.
gIOFirstPublishNotification Delivered when an IOService is registered, but only once per IOService instance. Some IOService's may be reregistered when their state is changed.
gIOMatchedNotification Delivered when an IOService has been matched with all client drivers, and they have been probed and started.
gIOFirstMatchNotification Delivered when an IOService has been matched with all client drivers, but only once per IOService instance. Some IOService's may be reregistered when their state is changed.
gIOTerminatedNotification Delivered after an IOService has been terminated, during its finalize stage.
matchingA matching dictionary to restrict notifications to only matching IOServices. The dictionary will be released when the notification is removed - consuming the passed in reference.
handlerA C-function callback to deliver notifications.
selfAn instance reference for the callbacks use.
refA reference constant for the callbacks use
priorityA constant ordering all notifications of a each type.
Result: Returns an instance of an IONotifier object that can be used to control or destroy the notification request.

adjustBusy

Abstract: Adjusts the busyState of an IOService.
public:

virtual void adjustBusy( SInt32 delta );

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

Parameters

NameDescription
deltaThe delta to be applied to the IOService busy state.

attach

Abstract: Attaches an IOService client to a provider in the registry.
public:

virtual bool attach( IOService * provider );

This function called in an IOService client enters the client into the 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 registry will retain both the client and provider until they are detached.

Parameters

NameDescription
providerThe IOService object which will serve as this objects provider.
Result: false if the provider is inactive or on a resource failure, otherwise true.

causeInterrupt

Abstract: Cause a device interrupt to occur.
public:

virtual IOReturn causeInterrupt(int source);

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

Parameters

NameDescription
sourceThe index of the interrupt source in the device.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.

changeStateTo

public:

IOReturn changeStateTo( unsigned long ordinal );

The power-controlling driver calls the policy-maker here when it wants the device switched to a different power state. This is mildly ironic in that it is the controlling driver which does the switching, but it must do it this way so that the policy-maker can make sure the power domain is correct and to notify interested parties pre-change. When appropriate, the policy-maker will call the controlling driver and have it switch the device to the requested state in the usual way. This request by the controlling driver is sticky in that the policy-maker will not switch the device lower than this request, so if the driver needs power raised for some reason and then gets it and does what it needs, it should then rescind the request by requesting state zero. This will allow the policy-maker to control the device as usual.

Parameters

NameDescription
ordinalThis is the number, in the power state array, of the desired power state.
Result: The return code reflects the state of the policy-maker's internal queue of power changes and can be ignored by the caller.

changeStateToPriv

    protected:

IOReturn changeStateToPriv( unsigned long ordinal );

A policy-maker calls its superclass here to change the power state of the device. The superclass takes care of making sure the power domain state is appropriate and informing interested parties. It calls the controlling driver to make the change.

Parameters

NameDescription
ordinalThis is the number, in the power state array, of the desired power state.
Result: The return code reflects the state of the policy-maker's internal queue of power changes and can be ignored by the caller.

close

Abstract: Release active access to a provider.
public:

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

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

Parameters

NameDescription
forClientDesignates the client of the provider requesting the close.
optionsOptions available for the close. The provider family may implement options for close; IOService defines none.
argFamily specific arguments, ignored by IOService.

compareProperties

Abstract: Utility to compare a set of properties in a matching dictionary with an IOService's property table.
public:

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

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 property table, if compareProperty returns true for each key, success is return else failure.

Parameters

NameDescription
matchingThe matching dictionary, which must be non-zero.
keysA collection (eg. OSSet, OSArray, OSDictionary) which should contain OSStrings (or OSSymbols) that specify the property keys to be compared.
Result: if compareProperty returns true for each key in the collection, success is return else failure.

compareProperty

Abstract: Utility to compare a property in a matching dictionary with an IOService's property table.
public:

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

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'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.

Parameters

NameDescription
matchingThe matching dictionary, which must be non-zero.
keyThe dictionary key specifying the property to be compared, as an OSString (which includes OSSymbol).
Result: If the property does not exist in the matching table, true is returned. 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.

compareProperty

Abstract: Utility to compare a property in a matching dictionary with an IOService's property table.
public:

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

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'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.

Parameters

NameDescription
matchingThe matching dictionary, which must be non-zero.
keyThe dictionary key specifying the property to be compared, as a C-string.
Result: If the property does not exist in the matching table, true is returned. 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.

currentCapability

public:

virtual IOPMPowerFlags currentCapability( void );

Some object calls a policy-maker here to find out the current capability of a device. The policy-maker returns a copy of the capabilityFlags field for the current power state in the power state array.


currentPowerConsumption

public:

virtual unsigned long currentPowerConsumption( void );

Some object calls a policy-maker here to find out the current power consumption of a device. The policy-maker returns a copy of the staticPower field for the current power state in the power state array.


deRegisterInterestedDriver

public:

IOReturn deRegisterInterestedDriver( IOService * theDriver );

An IOService which has previously registered with a policy-maker as an interested driver calls the policy-maker here to withdraw its interest. The policy-maker removes it from its list of interested drivers.

Result: These bits describe the capability of the device in its current power state. They are not understood by the policy-maker; they come from the capabilityFlags field of the current power state in the power state array.

detach

Abstract: Detaches an IOService client from a provider in the registry.
public:

virtual void detach( IOService * provider );

This function called in an IOService client removes the client as a child of the provider in the service plane of the registry. If the provider is not a parent of the client this is a no-op, otherwise the registry will release both the client and provider.

Parameters

NameDescription
providerThe IOService object to detach from.

disableInterrupt

Abstract: Disable a device interrupt.
public:

virtual IOReturn disableInterrupt(int source);

Disable a device interrupt. It is the callers responsiblity to keep track of the enable state of the interrupt source.

Parameters

NameDescription
sourceThe index of the interrupt source in the device.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.

enableInterrupt

Abstract: Enable a device interrupt.
public:

virtual IOReturn enableInterrupt(int source);

Enable a device interrupt. It is the callers responsiblity to keep track of the enable state of the interrupt source.

Parameters

NameDescription
sourceThe index of the interrupt source in the device.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.

errnoFromReturn

Abstract: A utility to translate an IOReturn code to a BSD errno.
public:

virtual int errnoFromReturn( IOReturn rtn );

BSD defines its own return codes for its functions in sys/errno.h, and IOKit 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.

Parameters

NameDescription
rtnThe IOReturn code.
Result: The BSD errno or EIO if unknown.

finalize

Abstract: The last stage in an IOService destruction.
public:

virtual bool finalize( IOOptionBits options );

The finalize method is called in an inactive (ie. terminated) IOService 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.

Parameters

NameDescription
optionsThe options passed to the terminate method of the IOService are passed on to finalize.
Result: Returns true.

getBusyState

Abstract: Returns the busyState of an IOService.
public:

virtual UInt32 getBusyState( void );

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

Result: The busyState.

getClient

Abstract: Returns an IOService's primary client.
public:

virtual IOService * getClient( void ) const;

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.

Result: Returns the first client of the provider, or zero if the IOService is not attached into the registry. The client is retained while it is attached, and should not be released by the caller.

getClientIterator

Abstract: Returns an iterator over an IOService's clients.
public:

virtual OSIterator * getClientIterator( void ) const;

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

Result: Returns 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.

getDeviceMemory

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

virtual OSArray * getDeviceMemory( void );

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

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

getDeviceMemoryCount

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

virtual IOItemCount getDeviceMemoryCount( void );

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

Result: An integer count of the number of ranges available.

getDeviceMemoryWithIndex

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

virtual IODeviceMemory * getDeviceMemoryWithIndex( unsigned int index );

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

Parameters

NameDescription
indexAn index into the array of ranges assigned to the device.
Result: 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 mapDeviceMemory() which will create a device memory mapping.

getInterruptType

Abstract: Return the type of interrupt used for a device supplying hardware interrupts.
public:

virtual IOReturn getInterruptType(int source, int *interruptType);

This method will return the type of interrupt used by the device.

Parameters

NameDescription
sourceThe index of the interrupt source in the device.
interruptTypeThe 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.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.

getMatchingServices

Abstract: Finds the set of current published IOServices matching a matching dictionary.
public:

static OSIterator * getMatchingServices( OSDictionary * matching );

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

Parameters

NameDescription
matchingThe matching dictionary describing the desired IOServices.
Result: An instance of an iterator over a set of IOServices. To be released by the caller.

getOpenClientIterator

Abstract: Returns an iterator over an provider's clients that currently have opened the provider.
public:

virtual OSIterator * getOpenClientIterator( void ) const;

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.

Result: Returns an iterator over the clients which the provider 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.

getOpenProviderIterator

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

virtual OSIterator * getOpenProviderIterator( void ) const;

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.

Result: Returns 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.

getPMworkloop

public:

virtual IOWorkLoop *getPMworkloop( void );


getPlatform

Abstract: Returns a pointer to the platform expert instance for the machine.
public:

static IOPlatformExpert * getPlatform( void );

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

Result: A pointer to the IOPlatformExport instance. It should not be released by the caller.

getProvider

Abstract: Returns an IOService's primary provider.
public:

virtual IOService * getProvider( void ) const;

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

Result: Returns the first provider of the client, or zero if the IOService is not attached into the registry. The provider is retained while the client is attached, and should not be released by the caller.

getProviderIterator

Abstract: Returns an iterator over an IOService's providers.
public:

virtual OSIterator * getProviderIterator( void ) const;

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

Result: Returns 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.

getResources

Abstract: Allocate any needed resources for a published IOService before clients attach.
public:

virtual IOReturn getResources( void );

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

Result: Return an IOReturn code, kIOReturnSuccess is necessary for the IOService to be successfully used, otherwise the registration process for the object is halted.

getServiceRoot

Abstract: Returns a pointer to the root of the service plane.
public:

static IOService * getServiceRoot( void );

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

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

getState

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

virtual IOOptionBits getState( void ) const;

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

getWorkLoop

Abstract: Returns the current work loop or provider->getWorkLoop().
public:

virtual IOWorkLoop * getWorkLoop() const;

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 an entire dedicated thread. This data has to be accessed from a providers 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 providers work loop, i.e. the work loop which will make the completion call outs. In one fell swoop we avoid a potentially nasty deadlock 'cause a work loop's gate is recursive.

Result: Always returns a work loop, either the current work loop or it walks up the $link getProvider() chain calling getWorkLoop. Eventually it will reach a valid work loop based driver or the root of the io tree where it will return a system wide work loop. Returns 0 if it fails to find (or create)

handleClose

Abstract: Overrideable method to control the open / close behaviour of an IOService.
public:

virtual void handleClose( IOService * forClient, IOOptionBits options );

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 via open. The object is locked via lockForArbitration before handleClose is called.

Parameters

NameDescription
forClientDesignates the client of the provider requesting the close.
optionsOptions for the close, may be interpreted by the implementor of handleOpen.

handleIsOpen

Abstract: Overrideable method to control the open / close behaviour of an IOService.
public:

virtual bool handleIsOpen( const IOService * forClient ) const;

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 via open. The object is locked via lockForArbitration before handleIsOpen is called.

Parameters

NameDescription
forClientIf non-zero, isOpen returns the open state for that client. If zero is passed, isOpen returns the open state for all clients.
Result: Returns true if the specific, or any, client has the IOService open.

handleOpen

Abstract: Overrideable method to control the open / close behaviour of an IOService.
public:

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

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 via open. The object is locked via lockForArbitration before handleOpen is called.

Parameters

NameDescription
forClientDesignates the client of the provider requesting the open.
optionsOptions for the open, may be interpreted by the implementor of handleOpen.
Result: Return true if the open was successful, false otherwise.

initialPowerStateForDomainState

public:

virtual unsigned long initialPowerStateForDomainState( IOPMPowerFlags );

A policy-maker (usually its superclass) calls its controlling driver here to find out which power state the device is in, given the current power domain state. This happens once, when the policy-maker is initializing, and the controlling driver can use this to know what state the device is in initially.

Parameters

NameDescription
domainStateThese flags describe the character of domain power in the current state of the power domain. The flags are not understood by the calling policy-maker; they were passed to it by its power domain parent. They come from the outputPowerCharacter field of the current power state in the power domain's power state array.

This method is implemented in a simple way in IOService. It scans the power state array looking for the highest state whose inputPowerRequirement field exactly matches the parameter. If more intelligent determination is required, the power-controlling driver should implement the method and override the superclass.
Result: A state number is returned.

installNotification

Abstract: Add a persistant notification handler to be notified of IOService events.
public:

static IONotifier * installNotification( const OSSymbol * type, OSDictionary * matching, IOServiceNotificationHandler handler, OSObject * self, void * ref, SInt32 priority, OSIterator ** existing );

A lower level interface to addNotification that will install a handler and return the current set of IOServices that are in the specified state and match the matching dictionary.

Parameters

NameDescription
typeSee addNotification.
matchingSee addNotification.
handlerSee addNotification.
selfSee addNotification.
refSee addNotification.
prioritySee addNotification.
existingReturns an iterator over the set of IOServices that are currently in the specified state and match the matching dictionary.
Result: See addNotification.

instanceMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify a service instance match.
public:

static OSDictionary * instanceMatching( IOService * instance, OSDictionary * table = 0 );

This function creates matching properties that will match only the specified IOService instance.

Parameters

NameDescription
instanceThe IOService instance for which matching will be successful.
tableIf zero, instanceMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

isInactive

Abstract: Check the IOService has been terminated, and is in the process of being destroyed.
public:

inline bool isInactive( void ) const { return( 0 != (kIOServiceInactiveState & getState())); }

When an IOService 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.

Result: Returns true if the IOService has been terminated.

isOpen

Abstract: Determine whether a specific, or any, client has an IOService open.
public:

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

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

Parameters

NameDescription
forClientIf non-zero, isOpen returns the open state for that client. If zero is passed, isOpen returns the open state for all clients.
Result: Returns true if the specific, or any, client has the IOService open.

joinPMtree

public:

virtual void joinPMtree( IOService * driver );

A policy-maker calls its nub here when initializing, to be attached into the power management hierarchy. The default function is to call the platform expert, which knows how to do it. This method is overridden by a nub subclass which may either know how to do it, or may need to take other action.

This may be the only "power management" method used in a nub, meaning it may be called even if the nub is not initialized for power management.

Before the nub returns from this method, the caller will probably be called at "setParent" and "setAggressiveness" and possibly at "addChild" as it is added to me hierarchy.


lockForArbitration

Abstract: Locks an IOService against changes in state or ownership.
public:

virtual bool lockForArbitration( bool isSuccessRequired = true );

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

Parameters

NameDescription
isSuccessRequiredIf a request for access to an IOService should be denied if it is terminated, isSuccessRequired should passed as false, otherwise pass true.

makeUsable

public:

IOReturn makeUsable( void );

Some client of a device is asking that it become usable. Although this has not come from the policy-maker for the device, treat it exactly as if it had. In this way, subsequent requests for lower power from the policy-maker will pre-empt this request. We treat this as policy-maker request to switch to the highest power state.

Result: The return code reflects the state of the policy-maker's internal queue of power changes and can be ignored by the caller.

mapDeviceMemoryWithIndex

Abstract: Maps a physical range of a device.
public:

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

This method will create 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.

Parameters

NameDescription
indexAn index into the array of ranges assigned to the device.
Result: 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.

matchLocation

Abstract: Allows a registered IOService to direct location matching.
public:

virtual IOService * matchLocation( IOService * client );

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

Parameters

NameDescription
clientThe IOService at which matching is taking place.
Result: Returns the IOService instance to be used for location matching.

matchPropertyTable

Abstract: Allows a registered IOService to implement family specific matching.
public:

virtual bool matchPropertyTable( OSDictionary * table );

All matching on an IOService will call this method to allow a family writer to implement matching in addition to the generic methods provided by IOService. The implementor 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 if so. Note that since matching is also carried out by other parts of IOKit, the matching dictionary may contain properties the family does not understand - these should not be considered matching failures.

Parameters

NameDescription
tableThe dictionary of properties to be matched against.
Result: Returns false if the family considers the matching dictionary does not match in properties it understands, true otherwise.

maxCapabilityForDomainState

public:

virtual unsigned long maxCapabilityForDomainState( IOPMPowerFlags domainState );

A policy-maker (usually its superclass) calls its controlling driver here to find out the highest power state possible for a given power domain state. This happens when the power domain is changing state and the policy-maker wants to find out what states the device is capable of in the new domain state.

Parameters

NameDescription
domainStateThese flags describe the character of domain power in some domain power state. The flags are not understood by the calling policy-maker; they were passed to it by its power domain parent. They come from the outputPowerCharacter field of a state in the power domain's power state array.

This method is implemented in a simple way in IOService. It scans the power state array looking for the highest state whose inputPowerRequirement field exactly matches the parameter. If more intelligent determination is required, the power-controlling driver should implement the method and override the superclass.
Result: A state number is returned.

message

Abstract: Receive a generic message delivered from an attached provider.
public:

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

A provider may deliver messages via the message method to its clients informing them of state changes, for example kIOMessageServiceIsTerminated or kIOMessageServiceIsSuspended. Certain messages are defined by IOKit in IOMessage.h while others may family dependent. This method is implemented in the client to receive messages.

Parameters

NameDescription
typeA type defined in IOMessage.h or defined by the provider family.
providerThe provider from which the message originates.
argumentAn argument defined by the provider family, not used by IOService.
Result: An IOReturn code defined by the message type.

messageClient

Abstract: Send a generic message to an attached client.
public:

virtual IOReturn messageClient( UInt32 type, IOService * client, void * argument );

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

Parameters

NameDescription
typeA type defined in IOMessage.h or defined by the provider family.
clientA client of the IOService to send the message.
argumentAn argument defined by the provider family, not used by IOService.
Result: The return code from the client message call.

messageClients

Abstract: Send a generic message to all attached clients.
public:

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

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

Parameters

NameDescription
typeA type defined in IOMessage.h or defined by the provider family.
argumentAn argument defined by the provider family, not used by IOService.
Result: Any non-kIOReturnSuccess return codes returned by the clients, or kIOReturnSuccess if all return kIOReturnSuccess.

nameMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify an IOService name match.
public:

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

A very common matching criteria for IOService is based on its name. nameMatching will create a matching dictionary that specifies any IOService which respond sucessfully 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.

Parameters

NameDescription
nameThe service's name, as an OSString (which includes OSSymbol). Name matching is successful on IOService's which respond sucessfully to the IORegistryEntry method compareName.
tableIf zero, nameMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

nameMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify an IOService name match.
public:

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

A very common matching criteria for IOService is based on its name. nameMatching will create a matching dictionary that specifies any IOService which respond sucessfully 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.

Parameters

NameDescription
nameThe service's name, as a const C-string. Name matching is successful on IOService's which respond sucessfully to the IORegistryEntry method compareName.
tableIf zero, nameMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

newTemperature

public:

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

A thermal-zone driver calls its policy-maker here to tell it that the temperature in the zone has changed. The thermal-zone policy-maker uses this information to manage its thermal zone.

Parameters

NameDescription
currentTempThis is the new temperature in the thermal zone.
whichZoneThis is a pointer to the controlling driver.

newUserClient

Abstract: A request to create a connection for a non kernel client.
public:

virtual IOReturn newUserClient( task_t owningTask, void * security_id, UInt32 type, IOUserClient ** handler );

A non kernel client may request a connection be opened via the IOServiceOpen() library function, which will call this method in an IOService. The rules & 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.

Parameters

NameDescription
owningTaskThe mach task requesting the connection.
security_idA token representing the access level for the task.
typeA constant specifying the type of connection to be created, specified by the caller of IOServiceOpen and interpreted only by the family.
handlerAn 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.
Result: A return code to be passed back to the caller of IOServiceOpen.

open

Abstract: Request active access to a provider.
public:

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

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

Parameters

NameDescription
forClientDesignates the client of the provider requesting the open.
optionsOptions 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.
Result: Return true if the open was successful, false otherwise.

overrideOffPriv

    protected:

IOReturn overrideOffPriv( void );

When a policy-maker has enabled the override, it can disable it again by calling this method in its superclass. This will allow the superclass to keep the device at the highest state required by itself, its power-controlling driver, and its children (when the power domain state allows). Turning off the override will initiate a power change if the policy-maker's desired power state is different from the maximum of the controlling driver's desire and the children's desires.

Result: The return code reflects the state of the policy-maker's internal queue of power changes and can be ignored by the caller.

overrideOnPriv

    protected:

IOReturn overrideOnPriv( void );

A policy-maker normally keeps its device at the highest state required by itself, its power-controlling driver, and its children (when the power domain state allows). There may be times, however, when a policy-maker needs the power state lower than its driver or its children desire, and when this is the case, it calls overrideOnPriv in its superclass to enable this override. When the override is on, the superclass keeps the device in the state desired by the policy-maker (requested via changeStateToPriv), regardless of the children's or driver's desire. Turning on the override will initiate a power change if the policy-maker's desired power state is different from the maximum of the controlling driver's desire and the children's desires.

Result: The return code reflects the state of the policy-maker's internal queue of power changes and can be ignored by the caller.

powerDomainDidChangeTo

public:

IOReturn powerDomainDidChangeTo( IOPMPowerFlags newPowerStateFlags );

When a power domain changes state, it notifies its children, which are policy-makers, by calling them at this method. It calls here after the changed power of the power domain has settled at the new level. A called policy-maker can return IOPMAckImplied to indicate that it is prepared for the change, or it can return a non-zero number to indicate that it is not prepared but will prepare and then call the parent at acknowledgePowerChange.

To prepare for a lowered power domain, the policy-maker informs all its interested parties of the new power state of its device. If any do not acknowledge immediately, then the policy-maker also will not.

To prepare for a raised power domain, the policy-maker calls its controlling driver to switch the device to the appropriate power state for the new domain state. When that is accomplished, the policy-maker informs all its interested parties of the new power state. If any interested driver or the controlling driver does not acknowledge immediately, then the policy-maker also will not.

Parameters

NameDescription
newPowerStateFlagsThese flags describe the character of power in the new domain state. They are not understood by the policy-maker. It asks the controlling driver to translate them into a state number within the power state array. (The policy-maker for the domain also doesn't understand the bits; they come from a outputPowerCharacter field of the power state array for the power domain.)

powerDomainWillChangeTo

public:

IOReturn powerDomainWillChangeTo( IOPMPowerFlags newPowerStateFlags );

When a power domain changes state, it notifies its children, which are policy-makers, by calling them at this method. It calls here before it makes the change, and a called policy-maker can return IOPMAckImplied to indicate that it is prepared for the change, or it can return a non-zero number to indicate that it is not prepared but will prepare and then call the parent at acknowledgePowerChange.

To prepare for a lowering of the power domain, the policy-maker informs all its interested parties of any resulting change in its device, and when they have all acknowledged, it calls its controlling driver to switch the device to an appropriate power state for the imminent domain state. If any interested driver or the controlling driver does not acknowledge immediately, then the policy-maker also will not.

To prepare for a raising of the power domain, the policy-maker informs all its interested parties of any resulting change in its device. If any do not acknowledge immediately, then the policy-maker also will not.

Parameters

NameDescription
newPowerStateFlagsThese flags describe the character of power in the imminent domain state. They are not understood by the policy-maker. It asks the controlling driver to translate them into a state number within the power state array. (The policy-maker for the domain also doesn't understand the bits; they come from a outputPowerCharacter field of the power state array for the power domain.)

powerStateDidChangeTo

public:

virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags, unsigned long, IOService* );

A policy-maker informs interested parties that its device has changed to a different power state. Interested parties are those that have registered for this notification via registerInterestedDriver and also the power-controlling driver which is registered as an interested driver automatically when it registers as the controlling driver.

Parameters

NameDescription
capabilitiesThese flags describe the capability of the device in the new power state. They are not understood by the policy-maker; they come from the capabilityFlags field of the new state in the power state array.
stateNumberThis is the number of the state in the state array that the device has switched to.
whatDeviceThis points to the policy-maker, and it is used by a driver which is receiving power state change notifications for multiple devices.
Result: 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 in the policy-maker.

powerStateForDomainState

public:

virtual unsigned long powerStateForDomainState( IOPMPowerFlags domainState );

A policy-maker (usually its superclass) calls its controlling driver here 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 the policy-maker wants to find out the effect of the change.

Parameters

NameDescription
domainStateThese flags describe the character of domain power in some domain power state. The flags are not understood by the calling policy-maker; they were passed to it by its power domain parent. They come from the outputPowerCharacter field of a state in the power domain's power state array.

This method is implemented in a simple way in IOService. It scans the power state array looking for the highest state whose inputPowerRequirement field exactly matches the parameter. If more intelligent determination is required, the power-controlling driver should implement the method and override the superclass.
Result: A state number is returned.

powerStateWillChangeTo

public:

virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags, unsigned long, IOService* );

A policy-maker informs interested parties that its device is about to change to a different power state. Interested parties are those that have registered for this notification via registerInterestedDriver and also the power-controlling driver which is registered as an interested driver automatically when it registers as the controlling driver.

Parameters

NameDescription
capabilitiesThese flags describe the capability of the device in the new power state. They are not understood by the policy-maker; they come from the capabilityFlags field of the new state in the power state array.
stateNumberThis is the number of the state in the state array that the device is switching to.
whatDeviceThis points to the policy-maker, and it is used by a driver which is receiving power state change notifications for multiple devices.
Result: 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 in the policy-maker.

probe

Abstract: During an IOService instantiation probe a matched service to see if it can be used.
public:

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

The registration process for an IOService (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.

Parameters

NameDescription
providerThe registered IOService which matches a driver personality's matching dictionary.
scorePointer 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 Probe Score property in the drivers property table, or kIODefaultProbeScore if none is specified. The probe method may alter the score to affect start order.
Result: Returns 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.

publishResource

Abstract: Use the resource service to publish a property.
public:

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

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

Parameters

NameDescription
keyA C-string key that globally identifies the object.
Theobject to be published.

publishResource

Abstract: Use the resource service to publish a property.
public:

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

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

Parameters

NameDescription
keyAn OSSymbol key that globally identifies the object.
Theobject to be published.

registerControllingDriver

public:

IOReturn registerControllingDriver( IOService* controllingDriver, IOPMPowerState* powerStates, unsigned long numberOfStates );

A driver calls a policy-maker here to volunteer to control power to the device. If the policy-maker accepts the volunteer, it adds the volunteer to its list of interested drivers, and it will call the volunteer at appropriate times to switch the power state of the device.

Parameters

NameDescription
controllingDriverThis points to the calling driver.
powerStatesThis is an array of power states which the driver can deal with. If this array is no less rich than one supplied by an earlier volunteer, then the policy-maker uses the calling driver as its power-controlling driver.
numberOfStatesThe number of power states in the array. Power states are defined in pwr_mgt/IOPMpowerState.h.
Result: IOPMNoErr is returned. There are various error conditions possible which prevent the policy-maker from accepting the new power state array. These conditions are logged in the power managment event log, but not returned to the caller.

registerInterestedDriver

public:

IOPMPowerFlags registerInterestedDriver( IOService* theDriver );

Some IOService calls a policy-maker here to register interest in the changing power state of its device.

Parameters

NameDescription
theDriverThe policy-maker adds this pointer to the calling IOService to its list of interested drivers. It informs drivers on this list pre- and post-power change.
Result: The policy-maker returns flags describing the capability of the device in its current power state. The policy-maker does not interpret these flags or understand them; they come from the power state array, and are understood only by interested drivers and perhaps the power-controlling driver. If the current power state is not yet defined, zero is returned. This is the case when the policy-maker is not yet in the power domain hierarchy or when it doesn't have a power-controlling driver yet.

registerInterrupt

Abstract: Register a C-function interrupt handler for a device supplying interrupts.
public:

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

This method will install 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 an IOWorkLoop based abstraction for interrupt delivery that may be more appropriate for work loop based drivers.

Parameters

NameDescription
sourceThe index of the interrupt source in the device.
targetAn object instance to be passed to the interrupt handler.
handlerThe C-function to be 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.
refConA reference constant for the handler's use.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.
kIOReturnNoResources is returned if the interrupt already has an installed handler.

registerService

Abstract: Start the registration process for a newly discovered IOService.
public:

virtual void registerService( IOOptionBits options = 0 );

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.

Parameters

NameDescription
optionsThe default zero options mask is recommended & should be used in most cases. The registration process is usually asynchronous, with possible driver probing & 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.

removeChild

public:

virtual IOReturn removeChild( IOService * theChild );

A power domain policy-maker is called here to tell it that one of its enclosed members is disappearing. This happens when a device policy-maker hands off its responsibility to another policy-maker or when its device disappears.


requestDomainState

public:

IOReturn requestDomainState( IOPMPowerFlags desiredState, IOService* whichChild, unsigned long specificationFlags );

The child of a power domain calls it parent here to request power of a certain character. It does this after lowering power in its own device which allows it to tolerate lower power in the domain, and it does this if it needs more power for its device than is currently available in the domain.

Parameters

NameDescription
desiredStateThese flags describe the power required for some state of the caller's device. They are not understood by either the child or the parent. They come from the power state array of the child (in the inputPowerRequirement field), and the parent compares them to bits in the outputPowerCharacter fields of its power state array.
whichChildThis points to the caller, so the power domain can know which child is requesting.
specificationFlagsThis value modifies the parent's choice of power state. If the parameter is IOPMNextHigherState, the parent will choose the lowest state which matches desiredState and which is higher than the current state. If the parameter is IOPMHighestState , the parent will choose the highest state which matches desiredState. If the parameter is IOPMNextLowerState, the parent will choose the highest state which matches desiredState and which is lower than the current state. If the parameter is IOPMLowestState, the parent will choose the lowest state which matches desiredState. A state matches desiredState if all the bits set in desiredState are also set in the outputPowerCharacter field of that state in the parent's power state array.
Result: The power domain parent returns IOPMBadSpecification if specificationFlags not wellformed. It returns IOPMNoSuchState if no state in its array satisfies the callers specification. It returns IOPMNotYetInitialized if it has not power state array yet to compare with. Otherwise it returns IOPMNoErr. In the last case it will initiate its change to the new state if it has a parent in the hierarchy (or is the root power domain.)

requestProbe

Abstract: An external request that hardware be re-scanned for devices.
public:

virtual IOReturn requestProbe( IOOptionBits options );

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.

Parameters

NameDescription
optionsFamily defined options, not interpreted by IOService.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.

resourceMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify a resource service match.
public:

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

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

Parameters

NameDescription
nameThe 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.
tableIf zero, resourceMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

resourceMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify a resource service match.
public:

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

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

Parameters

NameDescription
nameThe resource name, as a const C-string. Resource matching is successful when an object by that name has been published with the publishResource method.
tableIf zero, resourceMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

serviceMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify an IOService class match.
public:

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

A very common matching criteria for IOService is based on its class. serviceMatching will create 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.

Parameters

NameDescription
classNameThe class name, as an OSString (which includes OSSymbol). Class matching is successful on IOService's of this class or any subclass.
tableIf zero, serviceMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

serviceMatching

Abstract: Create a matching dictionary, or add matching properties to an existing dictionary, that specify an IOService class match.
public:

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

A very common matching criteria for IOService is based on its class. serviceMatching will create 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.

Parameters

NameDescription
classNameThe class name, as a const C-string. Class matching is successful on IOService's of this class or any subclass.
tableIf zero, serviceMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
Result: The matching dictionary created, or passed in, is returned on success, or zero on failure.

setAggressiveness

public:

virtual IOReturn setAggressiveness( unsigned long, unsigned long newLevel );

The parent of a policy-maker calls it here while broadcasting an aggressiveness factor around the power management hierarchy.

A policy-maker may want to intercept this call if it needs to do something with the new factor, like change its idle timeout, for example. A policy-maker which does intercept should call setAggressiveness in its superclass, though.

Parameters

NameDescription
typeThere are several aggressiveness factors which can be broadcast. One is a general aggressiveness factor, and the others are specific to parts of the system, like the hard drive or the display. A policy-maker takes action only on a factor that applies to its policy. These factor types (e.g. kPMSetGeneralAggressiveness) are defined in pwr_mgt/IOPM.h.
newLevelThis is the aggressiveness factor's new value.
Result: setAggressiveness returns IOPMNoErr.

setDeviceMemory

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

virtual void setDeviceMemory( OSArray * array );

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

Parameters

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

setIdleTimerPeriod

public:

virtual IOReturn setIdleTimerPeriod( unsigned long );

A policy-maker which uses the type 1 idleness determination provided by IOService calls its superclass here to set or change the idle timer period.

See activityTickle for a description of this idleness determination.

Parameters

NameDescription
periodThis is the desired idle timer period in seconds.
Result: The normal return is IOPMNoErr, but it is possible to return kIOReturnError if there was difficulty creating the timer event or the command queue, for example (which is done only on the first call.)

setParent

public:

virtual IOReturn setParent( IOService * theParent, IOPMPowerFlags currentState );

The Platform Expert or some other IOService calls a policy-maker here to inform it who its parent is in the power management hierarchy. This is part of the process of attaching a policy-maker into the hierarchy.

Parameters

NameDescription
theParentThis is a pointer to the parent IOService power domain.
currentStateThese flags describe the character of power in the power domain. If the policy-maker has a controlling driver, the policy-maker asks the driver, given this power domain state, what state it would be in, and then it tells the driver to assume that state.

setPowerState

public:

virtual IOReturn setPowerState( unsigned long powerStateOrdinal, IOService* whatDevice );

A policy-maker (usually its superclass) calls its controlling driver here to change the power state of its device.

Parameters

NameDescription
powerStateOrdinalThis is the number in the power state array of the state the driver is being instructed to switch to.
whatDeviceThis is a pointer to the policy-maker. It is useful when a single power-controlling driver controls multiple devices and needs to know for which device it is being called.
Result: The driver returns IOPMAckImplied if it has complied with the request when it returns. If it has started the process of changing power state but not finished it, it 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 in the policy-maker.

start

Abstract: During an IOService instantiation, the start method is called when the IOService has been selected to run on the provider.
public:

virtual bool start( IOService * provider );

The registration process for an IOService (the provider) includes instantiating possible driver clients. The start method is called in the client instance when it has been selected (by its probe score and match category) to be the winning client. The client is already attached to the provider when start is called.

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

stop

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

virtual void stop( IOService * provider );

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.


stringFromReturn

Abstract: A utility to supply a programmer friendly string from an IOReturn code.
public:

virtual const char * stringFromReturn( IOReturn rtn );

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.

Parameters

NameDescription
rtnThe IOReturn code.
Result: A pointer to a constant string, or zero if the return code is unknown.

temperatureCriticalForZone

public:

virtual IOReturn temperatureCriticalForZone( IOService * whichZone );

A policy-maker calls its parent power domain to alert it to critical temperature in some thermal zone.

Parameters

NameDescription
whichZoneThis is a pointer to the IOService policy-maker for the thermal zone which has reported critical temperature.
Result: temperatureCriticalForZone returns IOPMNoErr.

terminate

Abstract: Make an IOService inactive and begin its destruction.
public:

virtual bool terminate( IOOptionBits options = 0 );

Registering an IOService 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 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 sucessful though further progress in the destruction of the IOService 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 callers thread. After the IOService 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, 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 terminate process is inherently asynchronous since it will be deferred until all clients have chosen to close.

Parameters

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

terminateClient

Abstract: Passes a termination up the stack.
public:

virtual bool terminateClient( IOService * client, IOOptionBits options );

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

Parameters

NameDescription
clientThe client of the of the terminated provider.
optionsOptions originally passed to terminate, plus kIOServiceRecursing.
Result: result of the terminate request on the client.

unlockForArbitration

Abstract: Unlocks an IOService after a successful lockForArbitration.
public:

virtual void unlockForArbitration( void );

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


unregisterInterrupt

Abstract: Remove a C-function interrupt handler for a device supplying hardware interrupts.
public:

virtual IOReturn unregisterInterrupt(int source);

This method will remove a C-function interrupt handler previously installed with registerInterrupt.

Parameters

NameDescription
sourceThe index of the interrupt source in the device.
Result: An IOReturn code.
kIOReturnNoInterrupt is returned if the source is not valid.

waitForService

Abstract: Wait for a matching to service to be published.
public:

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

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

Parameters

NameDescription
matchingThe matching dictionary describing the desired IOService.
timeoutThe maximum time to wait.
Result: A published IOService matching the supplied dictionary.

waitQuiet

Abstract: Wait for an IOService's busyState to be zero.
public:

virtual IOReturn waitQuiet( mach_timespec_t * timeout = 0 );

Blocks the caller until an IOService is non busy.

Parameters

NameDescription
timeoutSpecifies a maximum time to wait.
Result: Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess.

youAreRoot

public:

IOReturn youAreRoot( void );

The Platform Expert instantiates the root power domain IOService and calls it here to inform it that it is the root power domain. (The only difference between the root domain and any other power domain is that the root has no parent and therefore never calls it.


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)