Lines Matching defs:IOService
36 This header contains the definition of the IOService class. IOService is the sole direct subclass of IORegistryEntry and is the base class of almost all I/O Kit family superclasses. IOService defines methods that support the life cycle of I/O Kit drivers. For more information on IOService, see {@linkdoc //apple_ref/doc/uid/TP0000011 I/O Kit Fundamentals}.
141 IOService * nub, int source );
146 @param newService The IOService object the notification is delivering. It is retained for the duration of the handler's invocation and doesn't need to be released by the handler. */
149 IOService * newService );
155 @param provider The IOService object who is delivering the notification. It is retained for the duration of the handler's invocation and doesn't need to be released by the handler.
160 UInt32 messageType, IOService * provider,
163 typedef void (*IOServiceApplierFunction)(IOService * service, void * context);
169 /*! @class IOService
171 @discussion 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.
173 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 OpenFirmware 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.
175 Matching dictionaries are associated with IOService classes by the catalogue, as driver property tables, and also supplied by clients of the notification APIs.
177 IOService provides matching based on C++ class (via OSMetaClass dynamic casting), registry entry name, a registry path to the service (which includes OpenFirmware paths), a name assigned by BSD, or by its location (its point of attachment).
179 <br><br>Driver Instantiation by IOService<br><br>
181 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.
183 When an IOService (the "provider") is published with the @link registerService registerService@/link 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 <code>kIOProbeScoreKey</code> ("IOProbeScore") property in the dictionary, or supplied with the notification.
195 After the drivers have all synchronously been started, the installed "matched" notifications that match the registered IOService are delivered.
197 <br><br>Properties used by IOService<br><br>
225 A string or collection of strings that match the provider's name. The comparison is implemented with the @link //apple_ref/cpp/instm/IORegistryEntry/compareNames/virtualbool/(OSObject*,OSString**) IORegistryEntry::compareNames@/link method, which supports a single string, or any collection (OSArray, OSSet, OSDictionary etc.) of strings. IOService objects with OpenFirmware 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 <code>kIONameMatchedKey</code> property.
254 A dictionary of properties that each must exist in the matching IOService and compare successfully with the <code>isEqualTo</code> method.
276 class IOService : public IORegistryEntry
278 OSDeclareDefaultStructors(IOService)
291 IOService * __provider;
293 IOService * __owner;
310 @discussion When an IOService is made inactive the default behavior is to also make any of its clients that have it as their only provider also inactive, in this way recursing the termination up the driver stack. This method allows an IOService object to override this behavior. Returning <code>true</code> from this method when passed a just terminated provider will cause the client to also be terminated.
315 virtual bool requestTerminate( IOService * provider, IOOptionBits options );
324 virtual bool willTerminate( IOService * provider, IOOptionBits options );
331 @param defer If there is pending I/O that requires this object to persist, and the provider is not opened by this object set <code>defer</code> to <code>true</code> and call the <code>IOService::didTerminate()</code> implementation when the I/O completes. Otherwise, leave <code>defer</code> set to its default value of <code>false</code>.
334 virtual bool didTerminate( IOService * provider, IOOptionBits options, bool * defer );
361 OSMetaClassDeclareReservedUsed(IOService, 0);
362 OSMetaClassDeclareReservedUsed(IOService, 1);
363 OSMetaClassDeclareReservedUsed(IOService, 2);
364 OSMetaClassDeclareReservedUsed(IOService, 3);
365 OSMetaClassDeclareReservedUsed(IOService, 4);
367 OSMetaClassDeclareReservedUnused(IOService, 5);
368 OSMetaClassDeclareReservedUnused(IOService, 6);
369 OSMetaClassDeclareReservedUnused(IOService, 7);
370 OSMetaClassDeclareReservedUnused(IOService, 8);
371 OSMetaClassDeclareReservedUnused(IOService, 9);
372 OSMetaClassDeclareReservedUnused(IOService, 10);
373 OSMetaClassDeclareReservedUnused(IOService, 11);
374 OSMetaClassDeclareReservedUnused(IOService, 12);
375 OSMetaClassDeclareReservedUnused(IOService, 13);
376 OSMetaClassDeclareReservedUnused(IOService, 14);
377 OSMetaClassDeclareReservedUnused(IOService, 15);
378 OSMetaClassDeclareReservedUnused(IOService, 16);
379 OSMetaClassDeclareReservedUnused(IOService, 17);
380 OSMetaClassDeclareReservedUnused(IOService, 18);
381 OSMetaClassDeclareReservedUnused(IOService, 19);
382 OSMetaClassDeclareReservedUnused(IOService, 20);
383 OSMetaClassDeclareReservedUnused(IOService, 21);
384 OSMetaClassDeclareReservedUnused(IOService, 22);
385 OSMetaClassDeclareReservedUnused(IOService, 23);
386 OSMetaClassDeclareReservedUnused(IOService, 24);
387 OSMetaClassDeclareReservedUnused(IOService, 25);
388 OSMetaClassDeclareReservedUnused(IOService, 26);
389 OSMetaClassDeclareReservedUnused(IOService, 27);
390 OSMetaClassDeclareReservedUnused(IOService, 28);
391 OSMetaClassDeclareReservedUnused(IOService, 29);
392 OSMetaClassDeclareReservedUnused(IOService, 30);
393 OSMetaClassDeclareReservedUnused(IOService, 31);
394 OSMetaClassDeclareReservedUnused(IOService, 32);
395 OSMetaClassDeclareReservedUnused(IOService, 33);
396 OSMetaClassDeclareReservedUnused(IOService, 34);
397 OSMetaClassDeclareReservedUnused(IOService, 35);
398 OSMetaClassDeclareReservedUnused(IOService, 36);
399 OSMetaClassDeclareReservedUnused(IOService, 37);
400 OSMetaClassDeclareReservedUnused(IOService, 38);
401 OSMetaClassDeclareReservedUnused(IOService, 39);
402 OSMetaClassDeclareReservedUnused(IOService, 40);
403 OSMetaClassDeclareReservedUnused(IOService, 41);
404 OSMetaClassDeclareReservedUnused(IOService, 42);
405 OSMetaClassDeclareReservedUnused(IOService, 43);
406 OSMetaClassDeclareReservedUnused(IOService, 44);
407 OSMetaClassDeclareReservedUnused(IOService, 45);
408 OSMetaClassDeclareReservedUnused(IOService, 46);
409 OSMetaClassDeclareReservedUnused(IOService, 47);
412 OSMetaClassDeclareReservedUnused(IOService, 48);
413 OSMetaClassDeclareReservedUnused(IOService, 49);
414 OSMetaClassDeclareReservedUnused(IOService, 50);
415 OSMetaClassDeclareReservedUnused(IOService, 51);
416 OSMetaClassDeclareReservedUnused(IOService, 52);
417 OSMetaClassDeclareReservedUnused(IOService, 53);
418 OSMetaClassDeclareReservedUnused(IOService, 54);
419 OSMetaClassDeclareReservedUnused(IOService, 55);
420 OSMetaClassDeclareReservedUnused(IOService, 56);
421 OSMetaClassDeclareReservedUnused(IOService, 57);
422 OSMetaClassDeclareReservedUnused(IOService, 58);
423 OSMetaClassDeclareReservedUnused(IOService, 59);
424 OSMetaClassDeclareReservedUnused(IOService, 60);
425 OSMetaClassDeclareReservedUnused(IOService, 61);
426 OSMetaClassDeclareReservedUnused(IOService, 62);
427 OSMetaClassDeclareReservedUnused(IOService, 63);
432 @abstract Accessor for IOService state bits, not normally needed or used outside IOService.
433 @result State bits for the IOService, eg. <code>kIOServiceInactiveState</code>, <code>kIOServiceRegisteredState</code>. */
438 @abstract Checks if the IOService object has been terminated, and is in the process of being destroyed.
439 @discussion When an IOService object is successfully terminated, it is immediately made inactive, which blocks further attach()es, matching or notifications occuring on the object. It remains inactive until the last client closes, and is then finalized and destroyed.
440 @result <code>true</code> if the IOService object has been terminated. */
447 @abstract Starts the registration process for a newly discovered IOService object.
448 @discussion This function allows an IOService subclass to be published and made available to possible clients, by starting the registration process and delivering notifications to registered clients. The object should be completely setup and ready to field requests from clients before <code>registerService</code> is called.
454 @abstract During an IOService object's instantiation, probes a matched service to see if it can be used.
455 @discussion The registration process for an IOService object (the provider) includes instantiating possible driver clients. The <code>probe</code> 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 <code>probe</code> method can be left unimplemented by IOService subclasses. The client is already attached to the provider when <code>probe</code> is called.
456 @param provider The registered IOService object that matches a driver personality's matching dictionary.
458 @result An IOService instance or zero when the probe is unsuccessful. In almost all cases the value of <code>this</code> 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 <code>start</code>. */
460 virtual IOService * probe( IOService * provider,
464 @abstract During an IOService object's instantiation, starts the IOService object that has been selected to run on the provider.
465 @discussion The <code>start</code> method of an IOService instance is called by its provider when it has been selected (due to its probe score and match category) as the winning client. The client is already attached to the provider when <code>start</code> is called.<br>Implementations of <code>start</code> must call <code>start</code> on their superclass at an appropriate point. If an implementation of <code>start</code> has already called <code>super::start</code> but subsequently determines that it will fail, it must call <code>super::stop</code> to balance the prior call to <code>super::start</code> and prevent reference leaks.
468 virtual bool start( IOService * provider );
471 @abstract During an IOService termination, the stop method is called in its clients before they are detached & it is destroyed.
472 @discussion The termination process for an IOService (the provider) will call stop in each of its clients, after they have closed the provider if they had it open, or immediately on termination. */
474 virtual void stop( IOService * provider );
480 @discussion IOService provides generic open and close semantics to track clients of a provider that have established an active datapath. The use of <code>open</code> and @link close close@/link, and rules regarding ownership are family defined, and defined by the @link handleOpen handleOpen@/link and @link handleClose handleClose@/link methods in the provider. Some families will limit access to a provider based on its open state.
482 @param options Options for the open. The provider family may implement options for open; IOService defines only <code>kIOServiceSeize</code> to request the device be withdrawn from its current owner.
485 virtual bool open( IOService * forClient,
491 @discussion IOService provides generic open and close semantics to track clients of a provider that have established an active datapath. The use of @link open open@/link and <code>close</code>, and rules regarding ownership are family defined, and defined by the @link handleOpen handleOpen@/link and @link handleClose handleClose@/link methods in the provider.
493 @param options Options available for the close. The provider family may implement options for close; IOService defines none.
494 @param arg Family specific arguments which are ignored by IOService. */
496 virtual void close( IOService * forClient,
500 @abstract Determines whether a specific, or any, client has an IOService object open.
501 @discussion Returns the open state of an IOService object with respect to the specified client, or when it is open by any client.
503 @result <codetrue</code if the specific, or any, client has the IOService object open. */
505 virtual bool isOpen( const IOService * forClient = 0 ) const;
508 @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses).
509 @discussion IOService calls this method in its subclasses in response to the @link open open@/link method, so the subclass may implement the request. The default implementation provides single owner access to an IOService object via <code>open</code>. The object is locked via @link lockForArbitration lockForArbitration@/link before <code>handleOpen</code> is called.
514 virtual bool handleOpen( IOService * forClient,
519 @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses).
520 @discussion IOService calls this method in its subclasses in response to the @link close close@/link method, so the subclass may implement the request. The default implementation provides single owner access to an IOService object via @link open open@/link. The object is locked via @link lockForArbitration lockForArbitration@/link before <code>handleClose</code> is called.
524 virtual void handleClose( IOService * forClient,
528 @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses).
529 @discussion IOService calls this method in its subclasses in response to the @link open open@/link method, so the subclass may implement the request. The default implementation provides single owner access to an IOService object via @link open open@/link. The object is locked via @link lockForArbitration lockForArbitration@/link before <code>handleIsOpen</code> is called.
531 @result <code>true</code> if the specific, or any, client has the IOService object open. */
533 virtual bool handleIsOpen( const IOService * forClient ) const;
538 @abstract Makes an IOService object inactive and begins its destruction.
539 @discussion Registering an IOService object informs possible clients of its existance and instantiates drivers that may be used with it; <code>terminate</code> involves the opposite process of informing clients that an IOService object is no longer able to be used and will be destroyed. By default, if any client has the service open, <code>terminate</code> fails. If the <code>kIOServiceRequired</code> flag is passed however, <code>terminate</code> will be successful though further progress in the destruction of the IOService object will not proceed until the last client has closed it. The service will be made inactive immediately upon successful termination, and all its clients will be notified via their @link message message@/link method with a message of type <code>kIOMessageServiceIsTerminated</code>. Both these actions take place on the caller's thread. After the IOService object is made inactive, further matching or attach calls will fail on it. Each client has its @link stop stop@/link method called upon their close of an inactive IOService object , or on its termination if they do not have it open. After <code>stop</code>, @link detach detach@/link is called in each client. When all clients have been detached, the @link finalize finalize@/link method is called in the inactive service. The termination process is inherently asynchronous because it will be deferred until all clients have chosen to close.
545 @abstract Finalizes the destruction of an IOService object.
546 @discussion The <code>finalize</code> method is called in an inactive (ie. terminated) IOService object after the last client has detached. IOService's implementation will call @link stop stop@/link, @link close close@/link, and @link detach detach@/link on each provider. When <code>finalize</code> returns, the object's retain count will have no references generated by IOService's registration process.
547 @param options The options passed to the @link terminate terminate@/link method of the IOService object are passed on to <code>finalize</code>.
558 @abstract Locks an IOService object against changes in state or ownership.
559 @discussion The registration, termination and open / close functions of IOService use <code>lockForArbtration</code> to single-thread access to an IOService object. <code>lockForArbitration</code> grants recursive access to the same thread.
560 @param isSuccessRequired If a request for access to an IOService object should be denied if it is terminated, pass <code>false</code>, otherwise pass <code>true</code>. */
565 @abstract Unlocks an IOService obkect after a successful @link lockForArbitration lockForArbitration@/link.
566 @discussion A thread granted exclusive access to an IOService object should release it with <code>unlockForArbitration</code>. */
572 @discussion When an IOService object is made inactive the default behavior is to also make any of its clients that have it as their only provider inactive, in this way recursing the termination up the driver stack. This method allows a terminated IOService object to override this behavior. Note the client may also override this behavior by overriding its @link terminate terminate@/link method.
577 virtual bool terminateClient( IOService * client, IOOptionBits options );
582 @abstract Returns the <code>busyState</code> of an IOService object.
583 @discussion Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService object, its <code>busyState</code> is increased by one. Change in <code>busyState</code> to or from zero also changes the IOService object's provider's <code>busyState</code> by one, which means that an IOService object is marked busy when any of the above activities is ocurring on it or any of its clients.
589 @abstract Adjusts the <code>busyState</code> of an IOService object.
590 @discussion Applies a delta to an IOService object's <code>busyState</code>. A change in the <code>busyState</code> to or from zero will change the IOService object's provider's <code>busyState</code> by one (in the same direction).
591 @param delta The delta to be applied to the IOService object's <code>busyState</code>. */
596 @abstract Waits for an IOService object's <code>busyState</code> to be zero.
597 @discussion Blocks the caller until an IOService object is non busy.
606 @abstract Allows a registered IOService object to implement family specific matching.
607 @discussion All matching on an IOService object will call this method to allow a family writer to implement matching in addition to the generic methods provided by IOService. The implementer should examine the matching dictionary passed to see if it contains properties the family understands for matching, and use them to match with the IOService object if so. Note that since matching is also carried out by other parts of the I/O Kit, the matching dictionary may contain properties the family does not understand - these should not be considered matching failures.
618 @abstract Allows a registered IOService object to direct location matching.
619 @discussion By default, a location matching property will be applied to an IOService object's provider. This method allows that behavior to be overridden by families.
620 @param client The IOService object at which matching is taking place.
621 @result Returns the IOService instance to be used for location matching. */
623 virtual IOService * matchLocation( IOService * client );
629 @discussion The resource service uses IOService's matching and notification to allow objects to be published and found by any I/O Kit client by a global name. <code>publishResource</code> makes an object available to anyone waiting for it or looking for it in the future.
637 @discussion The resource service uses IOService object's matching and notification to allow objects to be published and found by any I/O Kit client by a global name. <code>publishResource</code> makes an object available to anyone waiting for it or looking for it in the future.
647 @abstract Adds a persistant notification handler to be notified of IOService events.
648 @discussion IOService will deliver notifications of changes in state of an IOService object to registered clients. The type of notification is specified by a symbol, for example <code>gIOMatchedNotification</code> or <code>gIOTerminatedNotification</code>, and notifications will only include IOService objects that match the supplied matching dictionary. Notifications are ordered by a priority set with <code>addNotification</code>. When the notification is installed, its handler will be called with each of any currently existing IOService objects that are in the correct state (eg. registered) and match the supplied matching dictionary, avoiding races between finding preexisting and new IOService events. The notification request is identified by an instance of an IONotifier object, through which it can be enabled, disabled, or removed. <code>addNotification</code> consumes a retain count on the matching dictionary when the notification is removed.
649 @param type An OSSymbol identifying the type of notification and IOService state:
650 <br> <code>gIOPublishNotification</code> Delivered when an IOService object is registered.
651 <br> <code>gIOFirstPublishNotification</code> Delivered when an IOService object is registered, but only once per IOService instance. Some IOService objects may be reregistered when their state is changed.
652 <br> <code>gIOMatchedNotification</code> Delivered when an IOService object has been matched with all client drivers, and they have been probed and started.
653 <br> <code>gIOFirstMatchNotification</code> Delivered when an IOService object has been matched with all client drivers, but only once per IOService instance. Some IOService objects may be reregistered when their state is changed.
654 <br> <code>gIOTerminatedNotification</code> Delivered after an IOService object has been terminated, during its finalize stage.
655 @param matching A matching dictionary to restrict notifications to only matching IOService objects. The dictionary will be released when the notification is removed, consuming the passed-in reference.
670 @discussion Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched.
671 @param matching The matching dictionary describing the desired IOService object. <code>waitForService</code> consumes one reference of the matching dictionary.
673 @result A published IOService object matching the supplied dictionary. */
675 static IOService * waitForService( OSDictionary * matching,
679 @abstract Finds the set of current published IOService objects matching a matching dictionary.
680 @discussion Provides a method of finding the current set of published IOService objects matching the supplied matching dictionary.
681 @param matching The matching dictionary describing the desired IOService objects.
682 @result An instance of an iterator over a set of IOService objects. To be released by the caller. */
687 @abstract Adds a persistant notification handler to be notified of IOService events.
688 @discussion A lower level interface to @link addNotification addNotification@/link that installs a handler and returns the current set of IOService objects that are in the specified state and match the matching dictionary.
695 @param existing Returns an iterator over the set of IOService objects that are currently in the specified state and match the matching dictionary.
708 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match.
709 @discussion A very common matching criteria for IOService object is based on its class. <code>serviceMatching</code> creates a matching dictionary that specifies any IOService object of a class, or its subclasses. The class is specified by name, and an existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.
710 @param className The class name, as a const C string. Class matching is successful on IOService objects of this class or any subclass.
718 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match.
719 @discussion A very common matching criteria for IOService object is based on its class. <code>serviceMatching</code> creates a matching dictionary that specifies any IOService of a class, or its subclasses. The class is specified by name, and an existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.
720 @param className The class name, as an OSString (which includes OSSymbol). Class matching is successful on IOService objects of this class or any subclass.
728 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match.
729 @discussion A very common matching criteria for IOService object is based on its name. <code>nameMatching</code> creates a matching dictionary that specifies any IOService object which responds successfully to the @link //apple_ref/cpp/instm/IORegistryEntry/compareName/virtualbool/(OSString*,OSString**) IORegistryEntry::compareName@/link method. An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.
730 @param name The service's name, as a const C string. Name matching is successful on IOService objects that respond successfully to the <code>IORegistryEntry::compareName</code> method.
738 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match.
739 @discussion A very common matching criteria for IOService object is based on its name. <code>nameMatching</code> creates a matching dictionary that specifies any IOService object which responds successfully to the @link //apple_ref/cpp/instm/IORegistryEntry/compareName/virtualbool/(OSString*,OSString**) IORegistryEntry::compareName@/link method. An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.
740 @param name The service's name, as an OSString (which includes OSSymbol). Name matching is successful on IOService objects that respond successfully to the <code>IORegistryEntry::compareName</code> method.
749 @discussion IOService maintains a resource service IOResources that allows objects to be published and found globally in the I/O Kit based on a name, using the standard IOService matching and notification calls.
759 @discussion IOService maintains a resource service IOResources that allows objects to be published and found globally in the I/O Kit based on a name, using the standard IOService matching and notification calls.
769 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService phandle match.
770 @discussion TODO A very common matching criteria for IOService is based on its name. nameMatching will create a matching dictionary that specifies any IOService which respond successfully to the IORegistryEntry method compareName. An existing dictionary may be passed in, in which case the matching properties will be added to that dictionary rather than creating a new one.
771 @param key The service's phandle, as a const UInt32. PHandle matching is successful on IOService objects that respond successfully to the IORegistryEntry method compareName.
772 @param value The service's phandle, as a const UInt32. PHandle matching is successful on IOService's which respond successfully to the IORegistryEntry method compareName.
781 @discussion This function creates matching properties that specify the location of a IOService object, as an embedded matching dictionary. This matching will be successful on an IOService object that attached to an IOService object which matches this location matching dictionary.
790 @abstract Compares a property in a matching dictionary with an IOService object's property table.
791 @discussion This is a helper function to aid in implementing @link matchPropertyTable matchPropertyTable@/link. If the property specified by <code>key</code> exists in the matching dictionary, it is compared with a property of the same name in the IOService object's property table. The comparison is performed with the <code>isEqualTo</code> 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.
794 @result <code>true</code> if the property does not exist in the matching table. If the property exists in the matching dictionary but not the IOService property table, failure is returned. Otherwise the result of calling the property from the matching dictionary's <code>isEqualTo</code> method with the IOService property as an argument is returned. */
799 @abstract Compares a property in a matching dictionary with an IOService object's property table.
800 @discussion This is a helper function to aid in implementing @link matchPropertyTable matchPropertyTable@/link. If the property specified by <code>key</code> exists in the matching dictionary, it is compared with a property of the same name in the IOService object's property table. The comparison is performed with the <code>isEqualTo</code> 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.
803 @result <code>true</code> if the property does not exist in the matching table. If the property exists in the matching dictionary but not the IOService property table, failure is returned. Otherwise the result of calling the property from the matching dictionary's <code>isEqualTo</code> method with the IOService property as an argument is returned. */
809 @abstract Compares a set of properties in a matching dictionary with an IOService object's property table.
810 @discussion This is a helper function to aid in implementing @link matchPropertyTable matchPropertyTable@/link. A collection of dictionary keys specifies properties in a matching dictionary to be compared, with <code>compareProperty</code>, with an IOService object's property table, if <code>compareProperty</code> returns <code>true</code> for each key, success is returned; otherwise failure.
821 @abstract Attaches an IOService client to a provider in the I/O Registry.
822 @discussion This function called in an IOService client enters the client into the I/O Registry as a child of the provider in the service plane. The provider must be active or the attach will fail. Multiple attach calls to the same provider are no-ops and return success. A client may be attached to multiple providers. Entering an object into the I/O Registry retains both the client and provider until they are detached.
823 @param provider The IOService object which will serve as this object's provider.
826 virtual bool attach( IOService * provider );
829 @abstract Detaches an IOService client from a provider in the I/O Registry.
830 @discussion This function called in an IOService client removes the client as a child of the provider in the service plane of the I/O Registry. If the provider is not a parent of the client this is a no-op, otherwise the I/O Registry releases both the client and provider.
831 @param provider The IOService object to detach from. */
833 virtual void detach( IOService * provider );
836 @abstract Returns an IOService object's primary provider.
837 @discussion This function called in an IOService client will return the provider to which it was first attached. Because the majority of IOService objects have only one provider, this is a useful simplification and also supports caching of the provider when the I/O Registry is unchanged.
838 @result The first provider of the client, or zero if the IOService object is not attached into the I/O Registry. The provider is retained while the client is attached, and should not be released by the caller. */
840 virtual IOService * getProvider( void ) const;
844 @discussion This function returns a valid work loop that a client can use to add an IOCommandGate to. The intention is that an IOService client has data that needs to be protected but doesn't want to pay the cost of a dedicated thread. This data has to be accessed from a provider's call-out context as well. So to achieve both of these goals the client creates an IOCommandGate to lock access to his data but he registers it with the provider's work loop, i.e. the work loop which will make the completion call-outs. This avoids a potential deadlock because the work loop gate uses a recursive lock, which allows the same lock to be held multiple times by a single thread.
850 @abstract Returns an iterator over an IOService object's providers.
851 @discussion For those few IOService objects that obtain service from multiple providers, this method supplies an iterator over a client's providers.
858 @discussion For those few IOService objects that obtain service from multiple providers, this method supplies an iterator over a client's providers, locking each in turn with @link lockForArbitration lockForArbitration@/link and returning those that have been opened by the client.
864 @abstract Returns an IOService object's primary client.
865 @discussion This function called in an IOService provider will return the first client to attach to it. For IOService objects which have only only one client, this may be a useful simplification.
866 @result The first client of the provider, or zero if the IOService object is not attached into the I/O Registry. The client is retained while it is attached, and should not be released by the caller. */
868 virtual IOService * getClient( void ) const;
871 @abstract Returns an iterator over an IOService object's clients.
872 @discussion For IOService objects that may have multiple clients, this method supplies an iterator over a provider's clients.
879 @discussion For IOService objects that may have multiple clients, this method supplies an iterator over a provider's clients, locking each in turn with @link lockForArbitration lockForArbitration@/link and returning those that have opened the provider.
886 @discussion The platform expert or other drivers may implement various functions to control hardware features. <code>callPlatformFunction</code> allows any IOService object to access these functions. Normally <code>callPlatformFunction</code> is called on a service's provider. The provider services the request or passes it to its provider. The system's IOPlatformExpert subclass catches functions it knows about and redirects them into other parts of the service plane. If the IOPlatformExpert subclass cannot execute the function, the base class is called. The IOPlatformExpert base class attempts to find a service to execute the function by looking up the function name in an IOResources name space. A service may publish a service using <code>publishResource(functionName, this)</code>. If no service can be found to execute the function an error is returned.
921 @result A pointer to the IOService instance at the root of the service plane. It should not be released by the caller. */
923 static IOService * getServiceRoot( void );
927 @discussion IOService maintains a resource service IOResources that allows objects to be published and found globally in the I/O Kit based on a name, using the standard IOService matching and notification calls.
930 static IOService * getResourceService( void );
935 @abstract Allocates any needed resources for a published IOService object before clients attach.
936 @discussion This method is called during the registration process for an IOService object if there are successful driver matches, before any clients attach. It allows for lazy allocation of resources to an IOService object when a matching driver is found.
937 @result An IOReturn code; <code>kIOReturnSuccess</code> is necessary for the IOService object to be successfully used, otherwise the registration process for the object is halted. */
1039 @param options Family defined options, not interpreted by IOService.
1051 @param argument An argument defined by the provider family, not used by IOService.
1054 virtual IOReturn message( UInt32 type, IOService * provider,
1061 @param client A client of the IOService to send the message.
1062 @param argument An argument defined by the provider family, not used by IOService.
1072 @param argument An argument defined by the provider family, not used by IOService.
1099 @discussion A non kernel client may request a connection be opened via the @link //apple_ref/c/func/IOServiceOpen IOServiceOpen@/link library function, which will call this method in an IOService object. The rules and capabilities of user level clients are family dependent, and use the functions of the IOUserClient class for support. IOService's implementation returns <code>kIOReturnUnsupported</code>, so any family supporting user clients must implement this method.
1118 @discussion Strings are available for the standard return codes in <code>IOReturn.h</code> in IOService, while subclasses may implement this method to interpret family dependent return codes.
1126 @discussion BSD defines its own return codes for its functions in <code>sys/errno.h</code>, and I/O Kit families may need to supply compliant results in BSD shims. Results are available for the standard return codes in <code>IOReturn.h</code> in IOService, while subclasses may implement this method to interpret family dependent return codes.
1150 static IOService * resources( void );
1155 virtual bool startCandidate( IOService * candidate );
1156 virtual IOService * getClientWithCategory( const OSSymbol * category );
1180 IOService * newService );
1196 void scheduleStop( IOService * provider );
1200 static void actionWillTerminate( IOService * victim, IOOptionBits options,
1202 static void actionDidTerminate( IOService * victim, IOOptionBits options );
1203 static void actionFinalize( IOService * victim, IOOptionBits options );
1204 static void actionStop( IOService * client, IOService * provider );
1206 virtual IOReturn resolveInterrupt(IOService *nub, int source);
1243 virtual void joinPMtree ( IOService * driver );
1258 IOService* controllingDriver,
1264 @abstract Allows an IOService object to register interest in the changing power state of a power-managed IOService object.
1265 @discussion Call <code>registerInterestedDriver</code> on the IOService object you are interested in receiving power state messages from, and pass a pointer to the interested driver (<code>this</code>) as an argument.
1275 virtual IOPMPowerFlags registerInterestedDriver ( IOService* theDriver );
1283 virtual IOReturn deRegisterInterestedDriver ( IOService * theDriver );
1298 virtual IOReturn acknowledgePowerChange ( IOService * whichDriver );
1387 The IOService superclass can manage idleness determination with a simple idle timer mechanism and this <code>activityTickle</code> call. To start this up, the driver calls its superclass's <code>setIdleTimerPeriod</code>. 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 <code>activityTickle</code> 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.
1391 If the driver is managing the idleness determination totally on its own, the value of the <code>type</code> parameter should be <code>kIOPMSubclassPolicy</code>, and the driver should override the <code>activityTickle</code> method. The superclass IOService implementation of <code>activityTickle</code> does nothing with the <code>kIOPMSubclassPolicy</code> argument.
1393 @param type When <code>type</code> is <code>kIOPMSubclassPolicy</code>, <code>activityTickle</code> is not handled in IOService and should be intercepted by the subclass. When <code>type</code> is <code>kIOPMSuperclassPolicy1</code>, an activity flag is set and the device state is checked. If the device has been powered down, it is powered up again.
1441 virtual IOReturn temperatureCriticalForZone ( IOService * whichZone );
1444 @abstract Informs the root power domain IOService object that is is the root power domain.
1445 @discussion The Platform Expert instantiates the root power domain IOService object and calls it with this method to inform it that it is the root power domain.
1464 @param theChild A pointer to the child IOService object.
1466 virtual IOReturn addPowerChild ( IOService * theChild );
1497 @discussion A driver using the idleness determination provided by IOService calls its superclass with this method to set or change the idle timer period. See @link activityTickle activityTickle@/link for a description of this type of idleness determination.
1554 IOService* whatDevice );
1565 Most drivers do not need to implement this method, and can rely upon the default IOService implementation. The IOService implementation scans the power state array looking for the highest state whose <code>inputPowerRequirement</code> field exactly matches the value of the <code>domainState</code> parameter. If more intelligent determination is required, the driver itself should implement the method and override the superclass's implementation.
1578 Most drivers do not need to implement this method, and can rely upon the default IOService implementation. The IOService implementation scans the power state array looking for the highest state whose <code>inputPowerRequirement</code> field exactly matches the value of the <code>domainState</code> parameter. If more intelligent determination is required, the power managed driver should implement the method and override the superclass's implementation.
1590 Most drivers do not need to implement this method, and can rely upon the default IOService implementation. The IOService implementation scans the power state array looking for the highest state whose <code>inputPowerRequirement</code> field exactly matches the value of the <code>domainState</code> parameter. If more intelligent determination is required, the power managed driver should implement the method and override the superclass's implementation.
1614 IOService* whatDevice);
1632 IOService* whatDevice);
1645 virtual IOReturn newTemperature ( long currentTemp, IOService * whichZone );
1751 static IOPMRequest * acquirePMRequest( IOService * target, UInt32 type );
1753 static void pmDriverCallout( IOService * from );