1/*
2 * Copyright (c) 1998-2016 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/*
29 * Copyright (c) 1998,1999 Apple Computer, Inc. All rights reserved.
30 *
31 * HISTORY
32 *
33 */
34/*!
35 @header
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}.
37
38 @seealso //apple_ref/doc/header/IORegistryEntry.h IORegistryEntry
39*/
40
41#ifndef _IOKIT_IOSERVICE_H
42#define _IOKIT_IOSERVICE_H
43
44#include <IOKit/IORegistryEntry.h>
45#include <IOKit/IOReturn.h>
46#include <IOKit/IODeviceMemory.h>
47#include <IOKit/IONotifier.h>
48#include <IOKit/IOLocks.h>
49
50#include <IOKit/IOKitDebug.h>
51#include <IOKit/IOInterrupts.h>
52
53#include <IOKit/pwr_mgt/IOPMpowerState.h>
54#include <IOKit/IOServicePM.h>
55#include <IOKit/IOReportTypes.h>
56
57extern "C" {
58#include <kern/thread_call.h>
59}
60
61#ifndef UINT64_MAX
62#define UINT64_MAX 18446744073709551615ULL
63#endif
64
65
66enum {
67 kIODefaultProbeScore = 0
68};
69
70// masks for getState()
71enum {
72 kIOServiceInactiveState = 0x00000001,
73 kIOServiceRegisteredState = 0x00000002,
74 kIOServiceMatchedState = 0x00000004,
75 kIOServiceFirstPublishState = 0x00000008,
76 kIOServiceFirstMatchState = 0x00000010
77};
78
79enum {
80 // options for registerService()
81 kIOServiceExclusive = 0x00000001,
82
83 // options for terminate()
84 kIOServiceRequired = 0x00000001,
85 kIOServiceTerminate = 0x00000004,
86
87 // options for registerService() & terminate()
88 kIOServiceSynchronous = 0x00000002,
89 // options for registerService()
90 kIOServiceAsynchronous = 0x00000008
91};
92
93// options for open()
94enum {
95 kIOServiceSeize = 0x00000001,
96 kIOServiceFamilyOpenOptions = 0xffff0000
97};
98
99// options for close()
100enum {
101 kIOServiceFamilyCloseOptions = 0xffff0000
102};
103
104typedef void * IONotificationRef;
105
106extern const IORegistryPlane * gIOServicePlane;
107extern const IORegistryPlane * gIOPowerPlane;
108
109extern const OSSymbol * gIOResourcesKey;
110extern const OSSymbol * gIOResourceMatchKey;
111extern const OSSymbol * gIOResourceMatchedKey;
112extern const OSSymbol * gIOProviderClassKey;
113extern const OSSymbol * gIONameMatchKey;
114extern const OSSymbol * gIONameMatchedKey;
115extern const OSSymbol * gIOPropertyMatchKey;
116extern const OSSymbol * gIOLocationMatchKey;
117extern const OSSymbol * gIOParentMatchKey;
118extern const OSSymbol * gIOPathMatchKey;
119extern const OSSymbol * gIOMatchCategoryKey;
120extern const OSSymbol * gIODefaultMatchCategoryKey;
121extern const OSSymbol * gIOMatchedServiceCountKey;
122
123extern const OSSymbol * gIOUserClientClassKey;
124extern const OSSymbol * gIOKitDebugKey;
125extern const OSSymbol * gIOServiceKey;
126
127extern const OSSymbol * gIOCommandPoolSizeKey;
128
129extern const OSSymbol * gIOPublishNotification;
130extern const OSSymbol * gIOFirstPublishNotification;
131extern const OSSymbol * gIOMatchedNotification;
132extern const OSSymbol * gIOFirstMatchNotification;
133extern const OSSymbol * gIOTerminatedNotification;
134extern const OSSymbol * gIOWillTerminateNotification;
135
136extern const OSSymbol * gIOGeneralInterest;
137extern const OSSymbol * gIOBusyInterest;
138extern const OSSymbol * gIOOpenInterest;
139extern const OSSymbol * gIOAppPowerStateInterest;
140extern const OSSymbol * gIOPriorityPowerStateInterest;
141extern const OSSymbol * gIOConsoleSecurityInterest;
142
143extern const OSSymbol * gIODeviceMemoryKey;
144extern const OSSymbol * gIOInterruptControllersKey;
145extern const OSSymbol * gIOInterruptSpecifiersKey;
146
147extern const OSSymbol * gIOBSDKey;
148extern const OSSymbol * gIOBSDNameKey;
149extern const OSSymbol * gIOBSDMajorKey;
150extern const OSSymbol * gIOBSDMinorKey;
151extern const OSSymbol * gIOBSDUnitKey;
152
153extern SInt32 IOServiceOrdering( const OSMetaClassBase * inObj1, const OSMetaClassBase * inObj2, void * ref );
154
155typedef void (*IOInterruptAction)( OSObject * target, void * refCon,
156 IOService * nub, int source );
157
158#ifdef __BLOCKS__
159typedef void (^IOInterruptActionBlock)(IOService * nub, int source);
160#endif /* __BLOCKS__ */
161
162/*! @typedef IOServiceNotificationHandler
163 @param target Reference supplied when the notification was registered.
164 @param refCon Reference constant supplied when the notification was registered.
165 @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. */
166
167typedef bool (*IOServiceNotificationHandler)( void * target, void * refCon,
168 IOService * newService );
169
170typedef bool (*IOServiceMatchingNotificationHandler)( void * target, void * refCon,
171 IOService * newService,
172 IONotifier * notifier );
173
174#ifdef __BLOCKS__
175typedef bool (^IOServiceMatchingNotificationHandlerBlock)(IOService * newService,
176 IONotifier * notifier );
177#endif /* __BLOCKS__ */
178
179
180/*! @typedef IOServiceInterestHandler
181 @param target Reference supplied when the notification was registered.
182 @param refCon Reference constant supplied when the notification was registered.
183 @param messageType Type of the message - IOKit defined in IOKit/IOMessage.h or family specific.
184 @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.
185 @param messageArgument An argument for message, dependent on its type.
186 @param argSize Non zero if the argument represents a struct of that size, used when delivering messages outside the kernel. */
187
188typedef IOReturn (*IOServiceInterestHandler)( void * target, void * refCon,
189 UInt32 messageType, IOService * provider,
190 void * messageArgument, vm_size_t argSize );
191
192#ifdef __BLOCKS__
193typedef IOReturn (^IOServiceInterestHandlerBlock)( uint32_t messageType, IOService * provider,
194 void * messageArgument, size_t argSize );
195#endif /* __BLOCKS__ */
196
197typedef void (*IOServiceApplierFunction)(IOService * service, void * context);
198typedef void (*OSObjectApplierFunction)(OSObject * object, void * context);
199
200class IOUserClient;
201class IOPlatformExpert;
202
203/*! @class IOService
204 @abstract The base class for most I/O Kit families, devices, and drivers.
205 @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.
206
207Types of service are specified with a matching dictionary that describes properties of the service. For example, a matching dictionary might describe any IOUSBDevice (or subclass), an IOUSBDevice with a certain class code, or a IOPCIDevice with a set of matching names or device & vendor IDs. Since the matching dictionary is interpreted by the family which created the service, as well as generically by IOService, the list of properties considered for matching depends on the familiy.
208
209Matching dictionaries are associated with IOService classes by the catalogue, as driver property tables, and also supplied by clients of the notification APIs.
210
211IOService provides matching based on C++ class (via OSMetaClass dynamic casting), registry entry name, a registry path to the service (which includes device tree paths), a name assigned by BSD, or by its location (its point of attachment).
212
213<br><br>Driver Instantiation by IOService<br><br>
214
215Drivers 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.
216
217When 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.
218
219Each entry in the list is then processed in order - for notifications, the notification is delivered, for driver property tables a lot more happens.
220
221The driver class is instantiated and <code>init()</code> called with its property table. The new driver instance is then attached to the provider, and has its @link probe probe@/link method called with the provider as an argument. The default <code>probe</code> method does nothing but return success, but a driver may implement this method to interrogate the provider to make sure it can work with it. It may also modify its probe score at this time. After probe, the driver is detached and the next in the list is considered (ie. attached, probed, and detached).
222
223When the probing phase is complete, the list consists of successfully probed drivers, in order of their probe score (after adjustment during the @link probe probe@/link call). The list is then divided into categories based on the <code>kIOMatchCategoryKey</code> property ("IOMatchCategory"); drivers without a match category are all considered in one default category. Match categories allow multiple clients of a provider to be attached and started, though the provider may also enforce open/close semantics to gain active access to it.
224
225For each category, the highest scoring driver in that category is attached to the provider, and its @link start start@/link method called. If <code>start</code> is successful, the rest of the drivers in the same match category are discarded, otherwise the next highest scoring driver is started, and so on.
226
227The driver should only consider itself in action when the start method is called, meaning it has been selected for use on the provider, and consuming that particular match category. It should also be prepared to be allocated, probed and freed even if the probe was successful.
228
229After the drivers have all synchronously been started, the installed "matched" notifications that match the registered IOService are delivered.
230
231<br><br>Properties used by IOService<br><br>
232
233 <code>kIOClassKey, extern const OSSymbol * gIOClassKey, "IOClass"</code>
234<br>
235<br>
236Class of the driver to instantiate on matching providers.
237<br>
238<br>
239 <code>kIOProviderClassKey, extern const OSSymbol * gIOProviderClassKey, "IOProviderClass"</code>
240<br>
241<br>
242Class of the provider(s) to be considered for matching, checked with OSDynamicCast so subclasses will also match.
243<br>
244<br>
245 <code>kIOProbeScoreKey, extern const OSSymbol * gIOProbeScoreKey, "IOProbeScore"</code>
246<br>
247<br>
248The probe score initially used to order multiple matching drivers.
249<br>
250<br>
251 <code>kIOMatchCategoryKey, extern const OSSymbol * gIOMatchCategoryKey, "IOMatchCategory"</code>
252<br>
253<br>
254A string defining the driver category for matching purposes. All drivers with no <code>IOMatchCategory</code> property are considered to be in the same default category. Only one driver in a category can be started on each provider.
255<br>
256<br>
257 <code>kIONameMatchKey, extern const OSSymbol * gIONameMatchKey, "IONameMatch"</code>
258<br>
259A 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 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.
260<br>
261Examples
262<pre>
263@textblock
264 <key>IONameMatch</key>
265 <string>pci106b,7</string>
266@/textblock
267</pre>
268
269For a list of possible matching names, a serialized array of strings should used, eg.
270<pre>
271@textblock
272 <key>IONameMatch</key>
273 <array>
274 <string>APPL,happy16</string>
275 <string>pci106b,7</string>
276 </array>
277@/textblock
278</pre>
279
280<br>
281 <code>kIONameMatchedKey, extern const OSSymbol * gIONameMatchedKey, "IONameMatched"</code>
282<br>
283The name successfully matched name from the <code>kIONameMatchKey</code> property will be left in the driver's property table as the <code>kIONameMatchedKey</code> property.
284<br>
285<br>
286 <code>kIOPropertyMatchKey, extern const OSSymbol * gIOPropertyMatchKey, "IOPropertyMatch"</code>
287<br>
288A dictionary of properties that each must exist in the matching IOService and compare successfully with the <code>isEqualTo</code> method.
289
290<pre>
291@textblock
292 <key>IOPropertyMatch</key>
293 <dictionary>
294 <key>APPL,happy16</key>
295 <string>APPL,meek8</string>
296 </dictionary>
297@/textblock
298</pre>
299
300<br>
301 <code>kIOUserClientClassKey, extern const OSSymbol * gIOUserClientClassKey, "IOUserClientClass"</code>
302<br>
303The class name that the service will attempt to allocate when a user client connection is requested. First the device nub is queried, then the nub's provider is queried by default.
304<br>
305<br>
306 <code>kIOKitDebugKey, extern const OSSymbol * gIOKitDebugKey, "IOKitDebug"</code>
307<br>
308Set some debug flags for logging the driver loading process. Flags are defined in <code>IOKit/IOKitDebug.h</code>, but <code>65535</code> works well.*/
309
310struct IOInterruptAccountingData;
311struct IOInterruptAccountingReporter;
312
313class IOService : public IORegistryEntry
314{
315 OSDeclareDefaultStructors(IOService)
316
317protected:
318/*! @struct ExpansionData
319 @discussion This structure will be used to expand the capablilties of this class in the future.
320 */
321 struct ExpansionData {
322 uint64_t authorizationID;
323 /*
324 * Variables associated with interrupt accounting. Consists of an array
325 * (that pairs reporters with opaque "statistics" objects), the count for
326 * the array, and a lock to guard both of the former variables. The lock
327 * is necessary as IOReporting will not update reports in a manner that is
328 * synchonized with the service (i.e, on a workloop).
329 */
330 IOLock * interruptStatisticsLock;
331 IOInterruptAccountingReporter * interruptStatisticsArray;
332 int interruptStatisticsArrayCount;
333 };
334
335/*! @var reserved
336 Reserved for future use. (Internal use only) */
337 APPLE_KEXT_WSHADOW_PUSH;
338 ExpansionData * reserved;
339 APPLE_KEXT_WSHADOW_POP;
340
341private:
342 IOService * __provider;
343 SInt32 __providerGeneration;
344 IOService * __owner;
345 IOOptionBits __state[2];
346 uint64_t __timeBusy;
347 uint64_t __accumBusy;
348 IOServicePM * pwrMgt;
349
350protected:
351 // TRUE once PMinit has been called
352 bool initialized;
353
354public:
355 // DEPRECATED
356 void * pm_vars;
357
358public:
359 /* methods available in Mac OS X 10.1 or later */
360/*! @function requestTerminate
361 @abstract Passes a termination up the stack.
362 @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.
363 @param provider The terminated provider of this object.
364 @param options Options originally passed to terminate, plus <code>kIOServiceRecursing</code>.
365 @result <code>true</code> if this object should be terminated now that its provider has been. */
366
367 virtual bool requestTerminate( IOService * provider, IOOptionBits options );
368
369/*! @function willTerminate
370 @abstract Passes a termination up the stack.
371 @discussion Notification that a provider has been terminated, sent before recursing up the stack, in root-to-leaf order.
372 @param provider The terminated provider of this object.
373 @param options Options originally passed to terminate.
374 @result <code>true</code>. */
375
376 virtual bool willTerminate( IOService * provider, IOOptionBits options );
377
378/*! @function didTerminate
379 @abstract Passes a termination up the stack.
380 @discussion Notification that a provider has been terminated, sent after recursing up the stack, in leaf-to-root order.
381 @param provider The terminated provider of this object.
382 @param options Options originally passed to terminate.
383 @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>.
384 @result <code>true</code>. */
385
386 virtual bool didTerminate( IOService * provider, IOOptionBits options, bool * defer );
387
388/*! @function nextIdleTimeout
389 @availability Mac OS X v10.4 and later
390 @abstract Allows subclasses to customize idle power management behavior.
391 @discussion Returns the next time that the device should idle into its next lower power state. Subclasses may override for custom idle behavior.
392
393 A power managed driver might override this method to provide a more sophisticated idle power off algorithm than the one defined by power management.
394 @param currentTime The current time
395 @param lastActivity The time of last activity on this device
396 @param powerState The device's current power state.
397 @result Returns the next time the device should idle off (in seconds, relative to the current time). */
398
399 virtual SInt32 nextIdleTimeout(AbsoluteTime currentTime,
400 AbsoluteTime lastActivity, unsigned int powerState);
401
402/*! @function systemWillShutdown
403 @availability Mac OS X v10.5 and later
404 @abstract Notifies members of the power plane of system shutdown and restart.
405 @discussion This function is called for all members of the power plane in leaf-to-root order. If a subclass needs to wait for a pending I/O, then the call to <code>systemWillShutdown</code> should be postponed until the I/O completes.
406
407 Any power managed driver (which has called @link joinPMtree joinPMtree@/link to join the power plane) interested in taking action at system shutdown or restart should override this method.
408 @param specifier <code>kIOMessageSystemWillPowerOff</code> or <code>kIOMessageSystemWillRestart</code>. */
409
410 virtual void systemWillShutdown( IOOptionBits specifier );
411
412/*! @function copyClientWithCategory
413 @availability Mac OS X v10.6 and later
414 @param category An OSSymbol corresponding to an IOMatchCategory matching property.
415 @result Returns a reference to the IOService child with the given category. The result should be released by the caller.
416*/
417
418 virtual IOService * copyClientWithCategory( const OSSymbol * category );
419
420public:
421/*! @function configureReport
422 @abstract configure IOReporting channels
423 @availability SPI on OS X v10.9 / iOS 7 and later
424
425 @param channels - channels to configure
426 @param action - enable/disable/size, etc
427 @param result - action-specific returned value
428 @param destination - action-specific default destination
429*/
430virtual IOReturn configureReport(IOReportChannelList *channels,
431 IOReportConfigureAction action,
432 void *result,
433 void *destination);
434
435/*! @function updateReport
436 @abstract request current data for the specified channels
437 @availability SPI on OS X 10.9 / iOS 7 and later
438
439 @param channels - channels to be updated
440 @param action - type/style of update
441 @param result - returned details about what was updated
442 @param destination - destination for this update (action-specific)
443*/
444virtual IOReturn updateReport(IOReportChannelList *channels,
445 IOReportUpdateAction action,
446 void *result,
447 void *destination);
448
449private:
450#if __LP64__
451 OSMetaClassDeclareReservedUsed(IOService, 0);
452 OSMetaClassDeclareReservedUsed(IOService, 1);
453 OSMetaClassDeclareReservedUnused(IOService, 2);
454 OSMetaClassDeclareReservedUnused(IOService, 3);
455 OSMetaClassDeclareReservedUnused(IOService, 4);
456 OSMetaClassDeclareReservedUnused(IOService, 5);
457 OSMetaClassDeclareReservedUnused(IOService, 6);
458 OSMetaClassDeclareReservedUnused(IOService, 7);
459#else
460 OSMetaClassDeclareReservedUsed(IOService, 0);
461 OSMetaClassDeclareReservedUsed(IOService, 1);
462 OSMetaClassDeclareReservedUsed(IOService, 2);
463 OSMetaClassDeclareReservedUsed(IOService, 3);
464 OSMetaClassDeclareReservedUsed(IOService, 4);
465 OSMetaClassDeclareReservedUsed(IOService, 5);
466 OSMetaClassDeclareReservedUsed(IOService, 6);
467 OSMetaClassDeclareReservedUsed(IOService, 7);
468#endif
469
470 OSMetaClassDeclareReservedUnused(IOService, 8);
471 OSMetaClassDeclareReservedUnused(IOService, 9);
472 OSMetaClassDeclareReservedUnused(IOService, 10);
473 OSMetaClassDeclareReservedUnused(IOService, 11);
474 OSMetaClassDeclareReservedUnused(IOService, 12);
475 OSMetaClassDeclareReservedUnused(IOService, 13);
476 OSMetaClassDeclareReservedUnused(IOService, 14);
477 OSMetaClassDeclareReservedUnused(IOService, 15);
478 OSMetaClassDeclareReservedUnused(IOService, 16);
479 OSMetaClassDeclareReservedUnused(IOService, 17);
480 OSMetaClassDeclareReservedUnused(IOService, 18);
481 OSMetaClassDeclareReservedUnused(IOService, 19);
482 OSMetaClassDeclareReservedUnused(IOService, 20);
483 OSMetaClassDeclareReservedUnused(IOService, 21);
484 OSMetaClassDeclareReservedUnused(IOService, 22);
485 OSMetaClassDeclareReservedUnused(IOService, 23);
486 OSMetaClassDeclareReservedUnused(IOService, 24);
487 OSMetaClassDeclareReservedUnused(IOService, 25);
488 OSMetaClassDeclareReservedUnused(IOService, 26);
489 OSMetaClassDeclareReservedUnused(IOService, 27);
490 OSMetaClassDeclareReservedUnused(IOService, 28);
491 OSMetaClassDeclareReservedUnused(IOService, 29);
492 OSMetaClassDeclareReservedUnused(IOService, 30);
493 OSMetaClassDeclareReservedUnused(IOService, 31);
494 OSMetaClassDeclareReservedUnused(IOService, 32);
495 OSMetaClassDeclareReservedUnused(IOService, 33);
496 OSMetaClassDeclareReservedUnused(IOService, 34);
497 OSMetaClassDeclareReservedUnused(IOService, 35);
498 OSMetaClassDeclareReservedUnused(IOService, 36);
499 OSMetaClassDeclareReservedUnused(IOService, 37);
500 OSMetaClassDeclareReservedUnused(IOService, 38);
501 OSMetaClassDeclareReservedUnused(IOService, 39);
502 OSMetaClassDeclareReservedUnused(IOService, 40);
503 OSMetaClassDeclareReservedUnused(IOService, 41);
504 OSMetaClassDeclareReservedUnused(IOService, 42);
505 OSMetaClassDeclareReservedUnused(IOService, 43);
506 OSMetaClassDeclareReservedUnused(IOService, 44);
507 OSMetaClassDeclareReservedUnused(IOService, 45);
508 OSMetaClassDeclareReservedUnused(IOService, 46);
509 OSMetaClassDeclareReservedUnused(IOService, 47);
510
511public:
512/*! @function getState
513 @abstract Accessor for IOService state bits, not normally needed or used outside IOService.
514 @result State bits for the IOService, eg. <code>kIOServiceInactiveState</code>, <code>kIOServiceRegisteredState</code>. */
515
516 virtual IOOptionBits getState( void ) const;
517
518/*! @function isInactive
519 @abstract Checks if the IOService object has been terminated, and is in the process of being destroyed.
520 @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.
521 @result <code>true</code> if the IOService object has been terminated. */
522
523 bool isInactive( void ) const;
524
525 /* Stack creation */
526
527/*! @function registerService
528 @abstract Starts the registration process for a newly discovered IOService object.
529 @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.
530 @param options The default zero options mask is recommended and should be used in most cases. The registration process is usually asynchronous, with possible driver probing and notification occurring some time later. <code>kIOServiceSynchronous</code> may be passed to carry out the matching and notification process for currently registered clients before returning to the caller. */
531
532 virtual void registerService( IOOptionBits options = 0 );
533
534/*! @function probe
535 @abstract During an IOService object's instantiation, probes a matched service to see if it can be used.
536 @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.
537 @param provider The registered IOService object that matches a driver personality's matching dictionary.
538 @param score Pointer to the current driver's probe score, which is used to order multiple matching drivers in the same match category. It defaults to the value of the <code>IOProbeScore</code> property in the drivers property table, or <code>kIODefaultProbeScore</code> if none is specified. The <code>probe</code> method may alter the score to affect start order.
539 @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>. */
540
541 virtual IOService * probe( IOService * provider,
542 SInt32 * score );
543
544/*! @function start
545 @abstract During an IOService object's instantiation, starts the IOService object that has been selected to run on the provider.
546 @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.
547 @result <code>true</code> if the start was successful; <code>false</code> otherwise (which will cause the instance to be detached and usually freed). */
548
549 virtual bool start( IOService * provider );
550
551/*! @function stop
552 @abstract During an IOService termination, the stop method is called in its clients before they are detached & it is destroyed.
553 @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. */
554
555 virtual void stop( IOService * provider );
556
557 /* Open / Close */
558
559/*! @function open
560 @abstract Requests active access to a provider.
561 @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.
562 @param forClient Designates the client of the provider requesting the open.
563 @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.
564 @param arg Family specific arguments which are ignored by IOService.
565 @result <code>true</code> if the open was successful; <code>false</code> otherwise. */
566
567 virtual bool open( IOService * forClient,
568 IOOptionBits options = 0,
569 void * arg = 0 );
570
571/*! @function close
572 @abstract Releases active access to a provider.
573 @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.
574 @param forClient Designates the client of the provider requesting the close.
575 @param options Options available for the close. The provider family may implement options for close; IOService defines none. */
576
577 virtual void close( IOService * forClient,
578 IOOptionBits options = 0 );
579
580/*! @function isOpen
581 @abstract Determines whether a specific, or any, client has an IOService object open.
582 @discussion Returns the open state of an IOService object with respect to the specified client, or when it is open by any client.
583 @param forClient If non-zero, <code>isOpen</code> returns the open state for that client. If zero is passed, <code>isOpen</code> returns the open state for all clients.
584 @result <code>true</code> if the specific, or any, client has the IOService object open. */
585
586 virtual bool isOpen( const IOService * forClient = 0 ) const;
587
588/*! @function handleOpen
589 @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses).
590 @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.
591 @param forClient Designates the client of the provider requesting the open.
592 @param options Options for the open, may be interpreted by the implementor of <code>handleOpen</code>.
593 @result <code>true</code>if the open was successful; <code>false</code> otherwise. */
594
595 virtual bool handleOpen( IOService * forClient,
596 IOOptionBits options,
597 void * arg );
598
599/*! @function handleClose
600 @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses).
601 @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.
602 @param forClient Designates the client of the provider requesting the close.
603 @param options Options for the close, may be interpreted by the implementor of @link handleOpen handleOpen@/link. */
604
605 virtual void handleClose( IOService * forClient,
606 IOOptionBits options );
607
608/*! @function handleIsOpen
609 @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses).
610 @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.
611 @param forClient If non-zero, <code>isOpen</code> returns the open state for that client. If zero is passed, <code>isOpen</code> returns the open state for all clients.
612 @result <code>true</code> if the specific, or any, client has the IOService object open. */
613
614 virtual bool handleIsOpen( const IOService * forClient ) const;
615
616 /* Stacking change */
617
618/*! @function terminate
619 @abstract Makes an IOService object inactive and begins its destruction.
620 @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.
621 @param options In most cases no options are needed. <code>kIOServiceSynchronous</code> may be passed to cause <code>terminate</code> to not return until the service is finalized. */
622
623 virtual bool terminate( IOOptionBits options = 0 );
624
625/*! @function finalize
626 @abstract Finalizes the destruction of an IOService object.
627 @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.
628 @param options The options passed to the @link terminate terminate@/link method of the IOService object are passed on to <code>finalize</code>.
629 @result <code>true</code>. */
630
631 virtual bool finalize( IOOptionBits options );
632
633/*! @function init
634 @abstract Initializes generic IOService data structures (expansion data, etc). */
635 virtual bool init( OSDictionary * dictionary = 0 ) APPLE_KEXT_OVERRIDE;
636
637/*! @function init
638 @abstract Initializes generic IOService data structures (expansion data, etc). */
639 virtual bool init( IORegistryEntry * from,
640 const IORegistryPlane * inPlane ) APPLE_KEXT_OVERRIDE;
641
642/*! @function free
643 @abstract Frees data structures that were allocated when power management was initialized on this service. */
644
645 virtual void free( void ) APPLE_KEXT_OVERRIDE;
646
647/*! @function lockForArbitration
648 @abstract Locks an IOService object against changes in state or ownership.
649 @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.
650 @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>. */
651
652 virtual bool lockForArbitration( bool isSuccessRequired = true );
653
654/*! @function unlockForArbitration
655 @abstract Unlocks an IOService obkect after a successful @link lockForArbitration lockForArbitration@/link.
656 @discussion A thread granted exclusive access to an IOService object should release it with <code>unlockForArbitration</code>. */
657
658 virtual void unlockForArbitration( void );
659
660#ifdef XNU_KERNEL_PRIVATE
661 static uint32_t isLockedForArbitration(IOService * service);
662#endif /* XNU_KERNEL_PRIVATE */
663
664
665/*! @function terminateClient
666 @abstract Passes a termination up the stack.
667 @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.
668 @param client The client of the terminated provider.
669 @param options Options originally passed to @link terminate terminate@/link, plus <code>kIOServiceRecursing</code>.
670 @result result of the terminate request on the client. */
671
672 virtual bool terminateClient( IOService * client, IOOptionBits options );
673
674 /* Busy state indicates discovery, matching or termination is in progress */
675
676/*! @function getBusyState
677 @abstract Returns the <code>busyState</code> of an IOService object.
678 @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.
679 @result The <code>busyState</code> value. */
680
681 virtual UInt32 getBusyState( void );
682
683/*! @function adjustBusy
684 @abstract Adjusts the <code>busyState</code> of an IOService object.
685 @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).
686 @param delta The delta to be applied to the IOService object's <code>busyState</code>. */
687
688 virtual void adjustBusy( SInt32 delta );
689
690 APPLE_KEXT_COMPATIBILITY_VIRTUAL
691 IOReturn waitQuiet(mach_timespec_t * timeout)
692 APPLE_KEXT_DEPRECATED;
693
694/*! @function waitQuiet
695 @abstract Waits for an IOService object's <code>busyState</code> to be zero.
696 @discussion Blocks the caller until an IOService object is non busy.
697 @param timeout The maximum time to wait in nanoseconds. Default is to wait forever.
698 @result Returns an error code if Mach synchronization primitives fail, <code>kIOReturnTimeout</code>, or <code>kIOReturnSuccess</code>. */
699
700 IOReturn waitQuiet(uint64_t timeout = UINT64_MAX);
701
702 /* Matching */
703
704/*! @function matchPropertyTable
705 @abstract Allows a registered IOService object to implement family specific matching.
706 @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.
707 @param table The dictionary of properties to be matched against.
708 @param score Pointer to the current driver's probe score, which is used to order multiple matching drivers in the same match category. It defaults to the value of the <code>IOProbeScore</code> property in the drivers property table, or <code>kIODefaultProbeScore</code> if none is specified.
709 @result <code>false</code> if the family considers the matching dictionary does not match in properties it understands; <code>true</code> otherwise. */
710
711 virtual bool matchPropertyTable( OSDictionary * table,
712 SInt32 * score );
713
714 virtual bool matchPropertyTable( OSDictionary * table );
715
716/*! @function matchLocation
717 @abstract Allows a registered IOService object to direct location matching.
718 @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.
719 @param client The IOService object at which matching is taking place.
720 @result Returns the IOService instance to be used for location matching. */
721
722 virtual IOService * matchLocation( IOService * client );
723
724 /* Resource service */
725
726/*! @function publishResource
727 @abstract Uses the resource service to publish a property.
728 @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.
729 @param key An OSSymbol key that globally identifies the object.
730 @param value The object to be published. */
731
732 static void publishResource( const OSSymbol * key, OSObject * value = 0 );
733
734/*! @function publishResource
735 @abstract Uses the resource service to publish a property.
736 @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.
737 @param key A C string key that globally identifies the object.
738 @param value The object to be published. */
739
740 static void publishResource( const char * key, OSObject * value = 0 );
741 virtual bool addNeededResource( const char * key );
742
743 /* Notifications */
744
745/*! @function addNotification
746 @abstract Deprecated use addMatchingNotification(). Adds a persistant notification handler to be notified of IOService events.
747 @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.
748 @param type An OSSymbol identifying the type of notification and IOService state:
749<br> <code>gIOPublishNotification</code> Delivered when an IOService object is registered.
750<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.
751<br> <code>gIOMatchedNotification</code> Delivered when an IOService object has been matched with all client drivers, and they have been probed and started.
752<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.
753<br> <code>gIOWillTerminateNotification</code> Delivered after an IOService object has been terminated, during its finalize stage. Delivered after any matching on the service has finished.
754<br> <code>gIOTerminatedNotification</code> Delivered immediately when an IOService object has been terminated, making it inactive.
755 @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.
756 @param handler A C function callback to deliver notifications.
757 @param target An instance reference for the callback's use.
758 @param ref A reference constant for the callback's use.
759 @param priority A constant ordering all notifications of a each type.
760 @result An instance of an IONotifier object that can be used to control or destroy the notification request. */
761
762 static IONotifier * addNotification(
763 const OSSymbol * type, OSDictionary * matching,
764 IOServiceNotificationHandler handler,
765 void * target, void * ref = 0,
766 SInt32 priority = 0 )
767 APPLE_KEXT_DEPRECATED;
768
769/*! @function addMatchingNotification
770 @abstract Adds a persistant notification handler to be notified of IOService events.
771 @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>addMatchingNotification</code> does not consume a reference on the matching dictionary when the notification is removed, unlike addNotification.
772 @param type An OSSymbol identifying the type of notification and IOService state:
773<br> <code>gIOPublishNotification</code> Delivered when an IOService object is registered.
774<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.
775<br> <code>gIOMatchedNotification</code> Delivered when an IOService object has been matched with all client drivers, and they have been probed and started.
776<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.
777<br> <code>gIOWillTerminateNotification</code> Delivered after an IOService object has been terminated, during its finalize stage. Delivered after any matching on the service has finished.
778<br> <code>gIOTerminatedNotification</code> Delivered immediately when an IOService object has been terminated, making it inactive.
779 @param matching A matching dictionary to restrict notifications to only matching IOService objects. The dictionary is retained while the notification is installed. (Differs from addNotification).
780 @param handler A C function callback to deliver notifications.
781 @param target An instance reference for the callback's use.
782 @param ref A reference constant for the callback's use.
783 @param priority A constant ordering all notifications of a each type.
784 @result An instance of an IONotifier object that can be used to control or destroy the notification request. */
785
786 static IONotifier * addMatchingNotification(
787 const OSSymbol * type, OSDictionary * matching,
788 IOServiceMatchingNotificationHandler handler,
789 void * target, void * ref = 0,
790 SInt32 priority = 0 );
791
792
793#ifdef __BLOCKS__
794 static IONotifier * addMatchingNotification(
795 const OSSymbol * type, OSDictionary * matching,
796 SInt32 priority,
797 IOServiceMatchingNotificationHandlerBlock handler);
798#endif /* __BLOCKS__ */
799
800/*! @function waitForService
801 @abstract Deprecated use waitForMatchingService(). Waits for a matching to service to be published.
802 @discussion Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched.
803 @param matching The matching dictionary describing the desired IOService object. <code>waitForService</code> consumes one reference of the matching dictionary.
804 @param timeout The maximum time to wait.
805 @result A published IOService object matching the supplied dictionary. */
806
807 static IOService * waitForService( OSDictionary * matching,
808 mach_timespec_t * timeout = 0);
809
810/*! @function waitForMatchingService
811 @abstract Waits for a matching to service to be published.
812 @discussion Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched.
813 @param matching The matching dictionary describing the desired IOService object. (Does not consume a reference of the matching dictionary - differs from waitForService() which does consume a reference on the matching dictionary.)
814 @param timeout The maximum time to wait in nanoseconds. Default is to wait forever.
815 @result A published IOService object matching the supplied dictionary. waitForMatchingService returns a reference to the IOService which should be released by the caller. (Differs from waitForService() which does not retain the returned object.) */
816
817 static IOService * waitForMatchingService( OSDictionary * matching,
818 uint64_t timeout = UINT64_MAX);
819
820/*! @function getMatchingServices
821 @abstract Finds the set of current published IOService objects matching a matching dictionary.
822 @discussion Provides a method of finding the current set of published IOService objects matching the supplied matching dictionary.
823 @param matching The matching dictionary describing the desired IOService objects.
824 @result An instance of an iterator over a set of IOService objects. To be released by the caller. */
825
826 static OSIterator * getMatchingServices( OSDictionary * matching );
827
828/*! @function copyMatchingService
829 @abstract Finds one of the current published IOService objects matching a matching dictionary.
830 @discussion Provides a method to find one member of the set of published IOService objects matching the supplied matching dictionary.
831 @param matching The matching dictionary describing the desired IOService object.
832 @result The IOService object or NULL. To be released by the caller. */
833
834 static IOService * copyMatchingService( OSDictionary * matching );
835
836public:
837 /* Helpers to make matching dictionaries for simple cases,
838 * they add keys to an existing dictionary, or create one. */
839
840/*! @function serviceMatching
841 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match.
842 @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.
843 @param className The class name, as a const C string. Class matching is successful on IOService objects of this class or any subclass.
844 @param table If zero, <code>serviceMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
845 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
846
847 static OSDictionary * serviceMatching( const char * className,
848 OSDictionary * table = 0 );
849
850/*! @function serviceMatching
851 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match.
852 @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.
853 @param className The class name, as an OSString (which includes OSSymbol). Class matching is successful on IOService objects of this class or any subclass.
854 @param table If zero, <code>serviceMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
855 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
856
857 static OSDictionary * serviceMatching( const OSString * className,
858 OSDictionary * table = 0 );
859
860/*! @function nameMatching
861 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match.
862 @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.
863 @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.
864 @param table If zero, <code>nameMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
865 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
866
867 static OSDictionary * nameMatching( const char * name,
868 OSDictionary * table = 0 );
869
870/*! @function nameMatching
871 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match.
872 @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.
873 @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.
874 @param table If zero, <code>nameMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
875 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
876
877 static OSDictionary * nameMatching( const OSString* name,
878 OSDictionary * table = 0 );
879
880/*! @function resourceMatching
881 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match.
882 @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.
883 @param name The resource name, as a const C string. Resource matching is successful when an object by that name has been published with the <code>publishResource</code> method.
884 @param table If zero, <code>resourceMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
885 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
886
887 static OSDictionary * resourceMatching( const char * name,
888 OSDictionary * table = 0 );
889
890/*! @function resourceMatching
891 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match.
892 @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.
893 @param name The resource name, as an OSString (which includes OSSymbol). Resource matching is successful when an object by that name has been published with the <code>publishResource</code> method.
894 @param table If zero, <code>resourceMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
895 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
896
897 static OSDictionary * resourceMatching( const OSString * name,
898 OSDictionary * table = 0 );
899
900
901/*! @function propertyMatching
902 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService phandle match.
903 @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.
904 @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.
905 @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.
906 @param table If zero, nameMatching will create a matching dictionary and return a reference to it, otherwise the matching properties are added to the specified dictionary.
907 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
908
909 static OSDictionary * propertyMatching( const OSSymbol * key, const OSObject * value,
910 OSDictionary * table = 0 );
911
912/*! @function registryEntryIDMatching
913 @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a IORegistryEntryID match.
914 @discussion <code>registryEntryIDMatching</code> creates a matching dictionary that specifies the IOService object with the assigned registry entry ID (returned by <code>IORegistryEntry::getRegistryEntryID()</code>). 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.
915 @param entryID The service's ID. Matching is successful on the IOService object that return that ID from the <code>IORegistryEntry::getRegistryEntryID()</code> method.
916 @param table If zero, <code>registryEntryIDMatching</code> creates a matching dictionary and returns a reference to it, otherwise the matching properties are added to the specified dictionary.
917 @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */
918
919 static OSDictionary * registryEntryIDMatching( uint64_t entryID,
920 OSDictionary * table = 0 );
921
922
923/*! @function addLocation
924 @abstract Adds a location matching property to an existing dictionary.
925 @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.
926 @param table The matching properties are added to the specified dictionary, which must be non-zero.
927 @result The location matching dictionary created is returned on success, or zero on failure. */
928
929 static OSDictionary * addLocation( OSDictionary * table );
930
931 /* Helpers for matching dictionaries. */
932
933/*! @function compareProperty
934 @abstract Compares a property in a matching dictionary with an IOService object's property table.
935 @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.
936 @param matching The matching dictionary, which must be non-zero.
937 @param key The dictionary key specifying the property to be compared, as a C string.
938 @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. */
939
940 virtual bool compareProperty( OSDictionary * matching,
941 const char * key );
942/*! @function compareProperty
943 @abstract Compares a property in a matching dictionary with an IOService object's property table.
944 @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.
945 @param matching The matching dictionary, which must be non-zero.
946 @param key The dictionary key specifying the property to be compared, as an OSString (which includes OSSymbol).
947 @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. */
948
949 virtual bool compareProperty( OSDictionary * matching,
950 const OSString * key );
951
952/*! @function compareProperties
953 @abstract Compares a set of properties in a matching dictionary with an IOService object's property table.
954 @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.
955 @param matching The matching dictionary, which must be non-zero.
956 @param keys A collection (eg. OSSet, OSArray, OSDictionary) which should contain OSStrings (or OSSymbols) that specify the property keys to be compared.
957 @result Success if <code>compareProperty</code> returns <code>true</code> for each key in the collection; otherwise failure. */
958
959 virtual bool compareProperties( OSDictionary * matching,
960 OSCollection * keys );
961
962 /* Client / provider accessors */
963
964/*! @function attach
965 @abstract Attaches an IOService client to a provider in the I/O Registry.
966 @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.
967 @param provider The IOService object which will serve as this object's provider.
968 @result <code>false</code> if the provider is inactive or on a resource failure; otherwise <code>true</code>. */
969
970 virtual bool attach( IOService * provider );
971
972/*! @function detach
973 @abstract Detaches an IOService client from a provider in the I/O Registry.
974 @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.
975 @param provider The IOService object to detach from. */
976
977 virtual void detach( IOService * provider );
978
979/*! @function getProvider
980 @abstract Returns an IOService object's primary provider.
981 @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.
982 @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. */
983
984 virtual IOService * getProvider( void ) const;
985
986/*! @function getWorkLoop
987 @abstract Returns the current work loop or <code>provider->getWorkLoop</code>.
988 @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.
989 @result A work loop, either the current work loop or it walks up the @link getProvider getProvider@/link chain calling <code>getWorkLoop</code>. Eventually it will reach a valid work loop-based driver or the root of the I/O tree, where it will return a system-wide work loop. Returns 0 if it fails to find (or create) a work loop.*/
990
991 virtual IOWorkLoop * getWorkLoop() const;
992
993/*! @function getProviderIterator
994 @abstract Returns an iterator over an IOService object's providers.
995 @discussion For those few IOService objects that obtain service from multiple providers, this method supplies an iterator over a client's providers.
996 @result 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. */
997
998 virtual OSIterator * getProviderIterator( void ) const;
999
1000/*! @function getOpenProviderIterator
1001 @abstract Returns an iterator over an client's providers that are currently opened by the client.
1002 @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.
1003 @result 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 <code>lockForArbitration</code>, protecting it from state changes. */
1004
1005 virtual OSIterator * getOpenProviderIterator( void ) const;
1006
1007/*! @function getClient
1008 @abstract Returns an IOService object's primary client.
1009 @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.
1010 @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. */
1011
1012 virtual IOService * getClient( void ) const;
1013
1014/*! @function getClientIterator
1015 @abstract Returns an iterator over an IOService object's clients.
1016 @discussion For IOService objects that may have multiple clients, this method supplies an iterator over a provider's clients.
1017 @result 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. */
1018
1019 virtual OSIterator * getClientIterator( void ) const;
1020
1021/*! @function getOpenClientIterator
1022 @abstract Returns an iterator over a provider's clients that currently have opened the provider.
1023 @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.
1024 @result An iterator over the clients that have opened the provider, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, and the current entry in the iteration is locked with <code>lockForArbitration</code>, protecting it from state changes. */
1025
1026 virtual OSIterator * getOpenClientIterator( void ) const;
1027
1028/*! @function callPlatformFunction
1029 @abstract Calls the platform function with the given name.
1030 @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.
1031 @param functionName Name of the function to be called. When <code>functionName</code> is a C string, <code>callPlatformFunction</code> converts the C string to an OSSymbol and calls the OSSymbol version of <code>callPlatformFunction</code>. This process can block and should not be used from an interrupt context.
1032 @param waitForFunction If <code>true</code>, <code>callPlatformFunction</code> will not return until the function has been called.
1033 @result An IOReturn code; <code>kIOReturnSuccess</code> if the function was successfully executed, <code>kIOReturnUnsupported</code> if a service to execute the function could not be found. Other return codes may be returned by the function.*/
1034
1035 virtual IOReturn callPlatformFunction( const OSSymbol * functionName,
1036 bool waitForFunction,
1037 void *param1, void *param2,
1038 void *param3, void *param4 );
1039
1040 virtual IOReturn callPlatformFunction( const char * functionName,
1041 bool waitForFunction,
1042 void *param1, void *param2,
1043 void *param3, void *param4 );
1044
1045
1046 /* Some accessors */
1047
1048/*! @function getPlatform
1049 @abstract Returns a pointer to the platform expert instance for the computer.
1050 @discussion This method provides an accessor to the platform expert instance for the computer.
1051 @result A pointer to the IOPlatformExpert instance. It should not be released by the caller. */
1052
1053 static IOPlatformExpert * getPlatform( void );
1054
1055/*! @function getPMRootDomain
1056 @abstract Returns a pointer to the power management root domain instance for the computer.
1057 @discussion This method provides an accessor to the power management root domain instance for the computer.
1058 @result A pointer to the power management root domain instance. It should not be released by the caller. */
1059
1060 static class IOPMrootDomain * getPMRootDomain( void );
1061
1062/*! @function getServiceRoot
1063 @abstract Returns a pointer to the root of the service plane.
1064 @discussion This method provides an accessor to the root of the service plane for the computer.
1065 @result A pointer to the IOService instance at the root of the service plane. It should not be released by the caller. */
1066
1067 static IOService * getServiceRoot( void );
1068
1069/*! @function getResourceService
1070 @abstract Returns a pointer to the IOResources service.
1071 @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.
1072 @result A pointer to the IOResources instance. It should not be released by the caller. */
1073
1074 static IOService * getResourceService( void );
1075
1076 /* Allocate resources for a matched service */
1077
1078/*! @function getResources
1079 @abstract Allocates any needed resources for a published IOService object before clients attach.
1080 @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.
1081 @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. */
1082
1083 virtual IOReturn getResources( void );
1084
1085 /* Device memory accessors */
1086
1087/*! @function getDeviceMemoryCount
1088 @abstract Returns a count of the physical memory ranges available for a device.
1089 @discussion This method returns the count of physical memory ranges, each represented by an IODeviceMemory instance, that have been allocated for a memory mapped device.
1090 @result An integer count of the number of ranges available. */
1091
1092 virtual IOItemCount getDeviceMemoryCount( void );
1093
1094/*! @function getDeviceMemoryWithIndex
1095 @abstract Returns an instance of IODeviceMemory representing one of a device's memory mapped ranges.
1096 @discussion This method returns a pointer to an instance of IODeviceMemory for the physical memory range at the given index for a memory mapped device.
1097 @param index An index into the array of ranges assigned to the device.
1098 @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 @link mapDeviceMemoryWithIndex mapDeviceMemoryWithIndex@/link, which creates a device memory mapping. */
1099
1100 virtual IODeviceMemory * getDeviceMemoryWithIndex( unsigned int index );
1101
1102/*! @function mapDeviceMemoryWithIndex
1103 @abstract Maps a physical range of a device.
1104 @discussion This method creates a mapping for the IODeviceMemory at the given index, with <code>IODeviceMemory::map(options)</code>. The mapping is represented by the returned instance of IOMemoryMap, which should not be released until the mapping is no longer required.
1105 @param index An index into the array of ranges assigned to the device.
1106 @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. */
1107
1108 virtual IOMemoryMap * mapDeviceMemoryWithIndex( unsigned int index,
1109 IOOptionBits options = 0 );
1110
1111/*! @function getDeviceMemory
1112 @abstract Returns the array of IODeviceMemory objects representing a device's memory mapped ranges.
1113 @discussion This method returns an array of IODeviceMemory objects representing the physical memory ranges allocated to a memory mapped device.
1114 @result An OSArray of IODeviceMemory objects, or zero if none are available. The array is retained by the provider, so is valid while attached. */
1115
1116 virtual OSArray * getDeviceMemory( void );
1117
1118/*! @function setDeviceMemory
1119 @abstract Sets the array of IODeviceMemory objects representing a device's memory mapped ranges.
1120 @discussion This method sets an array of IODeviceMemory objects representing the physical memory ranges allocated to a memory mapped device.
1121 @param array An OSArray of IODeviceMemory objects, or zero if none are available. The array will be retained by the object. */
1122
1123 virtual void setDeviceMemory( OSArray * array );
1124
1125 /* Interrupt accessors */
1126
1127/*! @function registerInterrupt
1128 @abstract Registers a C function interrupt handler for a device supplying interrupts.
1129 @discussion This method installs a C function interrupt handler to be called at primary interrupt time for a device's interrupt. Only one handler may be installed per interrupt source. IOInterruptEventSource provides a work loop based abstraction for interrupt delivery that may be more appropriate for work loop based drivers.
1130 @param source The index of the interrupt source in the device.
1131 @param target An object instance to be passed to the interrupt handler.
1132 @param handler The C function to be called at primary interrupt time when the interrupt occurs. The handler should process the interrupt by clearing the interrupt, or by disabling the source.
1133 @param refCon A reference constant for the handler's use.
1134 @result An IOReturn code.<br><code>kIOReturnNoInterrupt</code> is returned if the source is not valid; <code>kIOReturnNoResources</code> is returned if the interrupt already has an installed handler. */
1135
1136 virtual IOReturn registerInterrupt(int source, OSObject *target,
1137 IOInterruptAction handler,
1138 void *refCon = 0);
1139
1140#ifdef __BLOCKS__
1141/*! @function registerInterrupt
1142 @abstract Registers a block handler for a device supplying interrupts.
1143 @discussion This method installs a C function interrupt handler to be called at primary interrupt time for a device's interrupt. Only one handler may be installed per interrupt source. IOInterruptEventSource provides a work loop based abstraction for interrupt delivery that may be more appropriate for work loop based drivers.
1144 @param source The index of the interrupt source in the device.
1145 @param target An object instance to be passed to the interrupt handler.
1146 @param handler The block to be invoked at primary interrupt time when the interrupt occurs. The handler should process the interrupt by clearing the interrupt, or by disabling the source.
1147 @result An IOReturn code.<br><code>kIOReturnNoInterrupt</code> is returned if the source is not valid; <code>kIOReturnNoResources</code> is returned if the interrupt already has an installed handler. */
1148
1149 IOReturn registerInterruptBlock(int source, OSObject *target,
1150 IOInterruptActionBlock handler);
1151#endif /* __BLOCKS__ */
1152
1153/*! @function unregisterInterrupt
1154 @abstract Removes a C function interrupt handler for a device supplying hardware interrupts.
1155 @discussion This method removes a C function interrupt handler previously installed with @link registerInterrupt registerInterrupt@/link.
1156 @param source The index of the interrupt source in the device.
1157 @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */
1158
1159 virtual IOReturn unregisterInterrupt(int source);
1160
1161/*! @function addInterruptStatistics
1162 @abstract Adds a statistics object to the IOService for the given interrupt.
1163 @discussion This method associates a set of statistics and a reporter for those statistics with an interrupt for this IOService, so that we can interrogate the IOService for statistics pertaining to that interrupt.
1164 @param statistics The IOInterruptAccountingData container we wish to associate the IOService with.
1165 @param source The index of the interrupt source in the device. */
1166 IOReturn addInterruptStatistics(IOInterruptAccountingData * statistics, int source);
1167
1168/*! @function removeInterruptStatistics
1169 @abstract Removes any statistics from the IOService for the given interrupt.
1170 @discussion This method disassociates any IOInterruptAccountingData container we may have for the given interrupt from the IOService; this indicates that the the interrupt target (at the moment, likely an IOInterruptEventSource) is being destroyed.
1171 @param source The index of the interrupt source in the device. */
1172 IOReturn removeInterruptStatistics(int source);
1173
1174/*! @function getInterruptType
1175 @abstract Returns the type of interrupt used for a device supplying hardware interrupts.
1176 @param source The index of the interrupt source in the device.
1177 @param interruptType The interrupt type for the interrupt source will be stored here by <code>getInterruptType</code>.<br> <code>kIOInterruptTypeEdge</code> will be returned for edge-trigggered sources.<br><code>kIOInterruptTypeLevel</code> will be returned for level-trigggered sources.
1178 @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */
1179
1180 virtual IOReturn getInterruptType(int source, int *interruptType);
1181
1182/*! @function enableInterrupt
1183 @abstract Enables a device interrupt.
1184 @discussion It is the caller's responsiblity to keep track of the enable state of the interrupt source.
1185 @param source The index of the interrupt source in the device.
1186 @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */
1187
1188 virtual IOReturn enableInterrupt(int source);
1189
1190/*! @function disableInterrupt
1191 @abstract Synchronously disables a device interrupt.
1192 @discussion If the interrupt routine is running, the call will block until the routine completes. It is the caller's responsiblity to keep track of the enable state of the interrupt source.
1193 @param source The index of the interrupt source in the device.
1194 @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */
1195
1196 virtual IOReturn disableInterrupt(int source);
1197
1198/*! @function causeInterrupt
1199 @abstract Causes a device interrupt to occur.
1200 @discussion Emulates a hardware interrupt, to be called from task level.
1201 @param source The index of the interrupt source in the device.
1202 @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */
1203
1204 virtual IOReturn causeInterrupt(int source);
1205
1206/*! @function requestProbe
1207 @abstract Requests that hardware be re-scanned for devices.
1208 @discussion For bus families that do not usually detect device addition or removal, this method represents an external request (eg. from a utility application) to rescan and publish or remove found devices.
1209 @param options Family defined options, not interpreted by IOService.
1210 @result An IOReturn code. */
1211
1212 virtual IOReturn requestProbe( IOOptionBits options );
1213
1214 /* Generic API for non-data-path upstream calls */
1215
1216/*! @function message
1217 @abstract Receives a generic message delivered from an attached provider.
1218 @discussion A provider may deliver messages via the <code>message</code> method to its clients informing them of state changes, such as <code>kIOMessageServiceIsTerminated</code> or <code>kIOMessageServiceIsSuspended</code>. Certain messages are defined by the I/O Kit in <code>IOMessage.h</code> while others may be family dependent. This method is implemented in the client to receive messages.
1219 @param type A type defined in <code>IOMessage.h</code> or defined by the provider family.
1220 @param provider The provider from which the message originates.
1221 @param argument An argument defined by the provider family, not used by IOService.
1222 @result An IOReturn code defined by the message type. */
1223
1224 virtual IOReturn message( UInt32 type, IOService * provider,
1225 void * argument = 0 );
1226
1227/*! @function messageClient
1228 @abstract Sends a generic message to an attached client.
1229 @discussion A provider may deliver messages via the @link message message@/link method to its clients informing them of state changes, such as <code>kIOMessageServiceIsTerminated</code> or <code>kIOMessageServiceIsSuspended</code>. Certain messages are defined by the I/O Kit in <code>IOMessage.h</code> while others may be family dependent. This method may be called in the provider to send a message to the specified client, which may be useful for overrides.
1230 @param messageType A type defined in <code>IOMessage.h</code> or defined by the provider family.
1231 @param client A client of the IOService to send the message.
1232 @param messageArgument An argument defined by the provider family, not used by IOService.
1233 @param argSize Specifies the size of messageArgument, in bytes. If argSize is non-zero, messageArgument is treated as a pointer to argSize bytes of data. If argSize is 0 (the default), messageArgument is treated as an ordinal and passed by value.
1234 @result The return code from the client message call. */
1235
1236 virtual IOReturn messageClient( UInt32 messageType, OSObject * client,
1237 void * messageArgument = 0, vm_size_t argSize = 0 );
1238
1239/*! @function messageClients
1240 @abstract Sends a generic message to all attached clients.
1241 @discussion A provider may deliver messages via the @link message message@/link method to its clients informing them of state changes, such as <code>kIOMessageServiceIsTerminated</code> or <code>kIOMessageServiceIsSuspended</code>. Certain messages are defined by the I/O Kit in <code>IOMessage.h</code> while others may be family dependent. This method may be called in the provider to send a message to all the attached clients, via the @link messageClient messageClient@/link method.
1242 @param type A type defined in <code>IOMessage.h</code> or defined by the provider family.
1243 @param argument An argument defined by the provider family, not used by IOService.
1244 @param argSize Specifies the size of argument, in bytes. If argSize is non-zero, argument is treated as a pointer to argSize bytes of data. If argSize is 0 (the default), argument is treated as an ordinal and passed by value.
1245 @result Any non-<code>kIOReturnSuccess</code> return codes returned by the clients, or <code>kIOReturnSuccess</code> if all return <code>kIOReturnSuccess</code>. */
1246
1247 virtual IOReturn messageClients( UInt32 type,
1248 void * argument = 0, vm_size_t argSize = 0 );
1249
1250 virtual IONotifier * registerInterest( const OSSymbol * typeOfInterest,
1251 IOServiceInterestHandler handler,
1252 void * target, void * ref = 0 );
1253
1254#ifdef __BLOCKS__
1255 IONotifier * registerInterest(const OSSymbol * typeOfInterest,
1256 IOServiceInterestHandlerBlock handler);
1257#endif /* __BLOCKS__ */
1258
1259 virtual void applyToProviders( IOServiceApplierFunction applier,
1260 void * context );
1261
1262 virtual void applyToClients( IOServiceApplierFunction applier,
1263 void * context );
1264
1265 virtual void applyToInterested( const OSSymbol * typeOfInterest,
1266 OSObjectApplierFunction applier,
1267 void * context );
1268
1269 virtual IOReturn acknowledgeNotification( IONotificationRef notification,
1270 IOOptionBits response );
1271
1272 /* User client create */
1273
1274/*! @function newUserClient
1275 @abstract Creates a connection for a non kernel client.
1276 @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.
1277 @param owningTask The Mach task of the client thread in the process of opening the user client. Note that in Mac OS X, each process is based on a Mach task and one or more Mach threads. For more information on the composition of a Mach task and its relationship with Mach threads, see {@linkdoc //apple_ref/doc/uid/TP30000905-CH209-TPXREF103 "Tasks and Threads"}.
1278 @param securityID A token representing the access level for the task.
1279 @param type A constant specifying the type of connection to be created, specified by the caller of @link //apple_ref/c/func/IOServiceOpen IOServiceOpen@/link and interpreted only by the family.
1280 @param handler An instance of an IOUserClient object to represent the connection, which will be released when the connection is closed, or zero if the connection was not opened.
1281 @param properties A dictionary of additional properties for the connection.
1282 @result A return code to be passed back to the caller of <code>IOServiceOpen</code>. */
1283
1284 virtual IOReturn newUserClient( task_t owningTask, void * securityID,
1285 UInt32 type, OSDictionary * properties,
1286 IOUserClient ** handler );
1287
1288 virtual IOReturn newUserClient( task_t owningTask, void * securityID,
1289 UInt32 type, IOUserClient ** handler );
1290
1291 /* Return code utilities */
1292
1293/*! @function stringFromReturn
1294 @abstract Supplies a programmer-friendly string from an IOReturn code.
1295 @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.
1296 @param rtn The IOReturn code.
1297 @result A pointer to a constant string, or zero if the return code is unknown. */
1298
1299 virtual const char * stringFromReturn( IOReturn rtn );
1300
1301/*! @function errnoFromReturn
1302 @abstract Translates an IOReturn code to a BSD <code>errno</code>.
1303 @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.
1304 @param rtn The IOReturn code.
1305 @result The BSD <code>errno</code> or <code>EIO</code> if unknown. */
1306
1307 virtual int errnoFromReturn( IOReturn rtn );
1308
1309 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
1310 /* * * * * * * * * * end of IOService API * * * * * * * */
1311 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
1312
1313 /* for IOInterruptController implementors */
1314
1315 int _numInterruptSources;
1316 IOInterruptSource *_interruptSources;
1317
1318 /* overrides */
1319 virtual bool serializeProperties( OSSerialize * s ) const APPLE_KEXT_OVERRIDE;
1320
1321#ifdef KERNEL_PRIVATE
1322 /* Apple only SPI to control CPU low power modes */
1323 void setCPUSnoopDelay(UInt32 ns);
1324 UInt32 getCPUSnoopDelay();
1325#endif
1326 void requireMaxBusStall(UInt32 ns);
1327 void requireMaxInterruptDelay(uint32_t ns);
1328
1329 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
1330 /* * * * * * * * * * * * Internals * * * * * * * * * * * */
1331 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
1332
1333#ifdef XNU_KERNEL_PRIVATE
1334public:
1335 // called from other xnu components
1336 static void initialize( void );
1337 static void setPlatform( IOPlatformExpert * platform);
1338 static void setPMRootDomain( class IOPMrootDomain * rootDomain );
1339 static IOReturn catalogNewDrivers( OSOrderedSet * newTables );
1340 uint64_t getAccumulatedBusyTime( void );
1341 static void updateConsoleUsers(OSArray * consoleUsers, IOMessage systemMessage);
1342 static void consoleLockTimer(thread_call_param_t p0, thread_call_param_t p1);
1343 void setTerminateDefer(IOService * provider, bool defer);
1344 uint64_t getAuthorizationID( void );
1345 IOReturn setAuthorizationID( uint64_t authorizationID );
1346 void cpusRunning(void);
1347 void scheduleFinalize(bool now);
1348
1349private:
1350 static IOReturn waitMatchIdle( UInt32 ms );
1351 static IONotifier * installNotification(
1352 const OSSymbol * type, OSDictionary * matching,
1353 IOServiceMatchingNotificationHandler handler,
1354 void * target, void * ref,
1355 SInt32 priority, OSIterator ** existing );
1356#if !defined(__LP64__)
1357 static IONotifier * installNotification(
1358 const OSSymbol * type, OSDictionary * matching,
1359 IOServiceNotificationHandler handler,
1360 void * target, void * ref,
1361 SInt32 priority, OSIterator ** existing);
1362#endif /* !defined(__LP64__) */
1363#endif
1364
1365private:
1366 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1367 bool checkResources( void );
1368 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1369 bool checkResource( OSObject * matching );
1370
1371 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1372 void probeCandidates( OSOrderedSet * matches );
1373 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1374 bool startCandidate( IOService * candidate );
1375
1376public:
1377 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1378 IOService * getClientWithCategory( const OSSymbol * category )
1379 APPLE_KEXT_DEPRECATED;
1380 // copyClientWithCategory is the public replacement
1381
1382#ifdef XNU_KERNEL_PRIVATE
1383 /* Callable within xnu source only - but require vtable entries to be visible */
1384public:
1385#else
1386private:
1387#endif
1388 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1389 bool passiveMatch( OSDictionary * matching, bool changesOK = false);
1390 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1391 void startMatching( IOOptionBits options = 0 );
1392 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1393 void doServiceMatch( IOOptionBits options );
1394 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1395 void doServiceTerminate( IOOptionBits options );
1396
1397private:
1398
1399 bool matchPassive(OSDictionary * table, uint32_t options);
1400 bool matchInternal(OSDictionary * table, uint32_t options, unsigned int * did);
1401 static bool instanceMatch(const OSObject * entry, void * context);
1402
1403 static OSObject * copyExistingServices( OSDictionary * matching,
1404 IOOptionBits inState, IOOptionBits options = 0 );
1405
1406 static IONotifier * setNotification(
1407 const OSSymbol * type, OSDictionary * matching,
1408 IOServiceMatchingNotificationHandler handler,
1409 void * target, void * ref,
1410 SInt32 priority = 0 );
1411
1412 static IONotifier * doInstallNotification(
1413 const OSSymbol * type, OSDictionary * matching,
1414 IOServiceMatchingNotificationHandler handler,
1415 void * target, void * ref,
1416 SInt32 priority, OSIterator ** existing );
1417
1418 static bool syncNotificationHandler( void * target, void * ref,
1419 IOService * newService, IONotifier * notifier );
1420
1421 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1422 void deliverNotification( const OSSymbol * type,
1423 IOOptionBits orNewState, IOOptionBits andNewState );
1424
1425 OSArray * copyNotifiers(const OSSymbol * type,
1426 IOOptionBits orNewState, IOOptionBits andNewState);
1427
1428 bool invokeNotifiers(OSArray ** willSend);
1429 bool invokeNotifier( class _IOServiceNotifier * notify );
1430
1431 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1432 void unregisterAllInterest( void );
1433
1434 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1435 IOReturn waitForState( UInt32 mask, UInt32 value,
1436 mach_timespec_t * timeout = 0 );
1437
1438 IOReturn waitForState( UInt32 mask, UInt32 value, uint64_t timeout );
1439
1440 UInt32 _adjustBusy( SInt32 delta );
1441
1442 bool terminatePhase1( IOOptionBits options = 0 );
1443 void scheduleTerminatePhase2( IOOptionBits options = 0 );
1444 void scheduleStop( IOService * provider );
1445
1446 static void waitToBecomeTerminateThread( void );
1447 static void __attribute__((__noreturn__)) terminateThread( void * arg, wait_result_t unused );
1448 static void terminateWorker( IOOptionBits options );
1449 static void actionWillTerminate( IOService * victim, IOOptionBits options,
1450 OSArray * doPhase2List, void*, void * );
1451 static void actionDidTerminate( IOService * victim, IOOptionBits options,
1452 void *, void *, void *);
1453
1454 static void actionWillStop( IOService * victim, IOOptionBits options,
1455 void *, void *, void *);
1456 static void actionDidStop( IOService * victim, IOOptionBits options,
1457 void *, void *, void *);
1458
1459 static void actionFinalize( IOService * victim, IOOptionBits options,
1460 void *, void *, void *);
1461 static void actionStop( IOService * client, IOService * provider,
1462 void *, void *, void *);
1463
1464 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1465 IOReturn resolveInterrupt(IOService *nub, int source);
1466 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1467 IOReturn lookupInterrupt(int source, bool resolve, IOInterruptController **interruptController);
1468
1469#ifdef XNU_KERNEL_PRIVATE
1470 /* end xnu internals */
1471#endif
1472
1473 /* power management */
1474public:
1475
1476/*! @function PMinit
1477 @abstract Initializes power management for a driver.
1478 @discussion <code>PMinit</code> allocates and initializes the power management instance variables, and it should be called before accessing those variables or calling the power management methods. This method should be called inside the driver's <code>start</code> routine and must be paired with a call to @link PMstop PMstop@/link.
1479 Most calls to <code>PMinit</code> are followed by calls to @link joinPMtree joinPMtree@/link and @link registerPowerDriver registerPowerDriver@/link. */
1480
1481 virtual void PMinit( void );
1482
1483/*! @function PMstop
1484 @abstract Stop power managing the driver.
1485 @discussion Removes the driver from the power plane and stop its power management. This method is synchronous against any power management method invocations (e.g. <code>setPowerState</code> or <code>setAggressiveness</code>), so when this method returns it is guaranteed those power management methods will not be entered. Driver should not call any power management methods after this call.
1486 Calling <code>PMstop</code> cleans up for the three power management initialization calls: @link PMinit PMinit@/link, @link joinPMtree joinPMtree@/link, and @link registerPowerDriver registerPowerDriver@/link. */
1487
1488 virtual void PMstop( void );
1489
1490/*! @function joinPMtree
1491 @abstract Joins the driver into the power plane of the I/O Registry.
1492 @discussion A driver uses this method to call its nub when initializing (usually in its <code>start</code> routine after calling @link PMinit PMinit@/link), to be attached into the power management hierarchy (i.e., the power plane). A driver usually calls this method on the driver for the device that provides it power (this is frequently the nub).
1493 Before this call returns, the caller will probably be called at @link setPowerParent setPowerParent@/link and @link setAggressiveness setAggressiveness@/link and possibly at @link addPowerChild addPowerChild@/link as it is added to the hierarchy. This method may be overridden by a nub subclass.
1494 @param driver The driver to be added to the power plane, usually <code>this</code>. */
1495
1496 virtual void joinPMtree( IOService * driver );
1497
1498/*! @function registerPowerDriver
1499 @abstract Registers a set of power states that the driver supports.
1500 @discussion A driver defines its array of supported power states with power management in its power management initialization (its <code>start</code> routine). If successful, power management will call the driver to instruct it to change its power state through @link setPowerState setPowerState@/link.
1501 Most drivers do not need to override <code>registerPowerDriver</code>. A nub may override <code>registerPowerDriver</code> if it needs to arrange its children in the power plane differently than the default placement, but this is uncommon.
1502 @param controllingDriver A pointer to the calling driver, usually <code>this</code>.
1503 @param powerStates A driver-defined array of power states that the driver and device support. Power states are defined in <code>pwr_mgt/IOPMpowerState.h</code>.
1504 @param numberOfStates The number of power states in the array.
1505 @result <code>IOPMNoErr</code>. All errors are logged via <code>kprintf</code>. */
1506
1507 virtual IOReturn registerPowerDriver(
1508 IOService * controllingDriver,
1509 IOPMPowerState * powerStates,
1510 unsigned long numberOfStates );
1511
1512/*! @function registerInterestedDriver
1513 @abstract Allows an IOService object to register interest in the changing power state of a power-managed IOService object.
1514 @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.
1515 The interested driver is retained until the power interest is removed by calling <code>deRegisterInterestedDriver</code>.
1516 The interested driver should override @link powerStateWillChangeTo powerStateWillChangeTo@/link and @link powerStateDidChangeTo powerStateDidChangeTo@/link to receive these power change messages.
1517 Interested drivers must acknowledge power changes in <code>powerStateWillChangeTo</code> or <code>powerStateDidChangeTo</code>, either via return value or later calls to @link acknowledgePowerChange acknowledgePowerChange@/link.
1518 @param theDriver The driver of interest adds this pointer to the list of interested drivers. It informs drivers on this list before and after the power change.
1519 @result Flags describing the capability of the device in its current power state. If the current power state is not yet defined, zero is returned (this is the case when the driver is not yet in the power domain hierarchy or hasn't fully registered with power management yet). */
1520
1521 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1522 IOPMPowerFlags registerInterestedDriver( IOService * theDriver );
1523
1524/*! @function deRegisterInterestedDriver
1525 @abstract De-registers power state interest from a previous call to <code>registerInterestedDriver</code>.
1526 @discussion The retain from <code>registerInterestedDriver</code> is released. This method is synchronous against any <code>powerStateWillChangeTo</code> or <code>powerStateDidChangeTo</code> call targeting the interested driver, so when this method returns it is guaranteed those interest handlers will not be entered.
1527 Most drivers do not need to override <code>deRegisterInterestedDriver</code>.
1528 @param theDriver The interested driver previously passed into @link registerInterestedDriver registerInterestedDriver@/link.
1529 @result A return code that can be ignored by the caller. */
1530
1531 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1532 IOReturn deRegisterInterestedDriver( IOService * theDriver );
1533
1534/*! @function acknowledgePowerChange
1535 @abstract Acknowledges an in-progress power state change.
1536 @discussion When power management informs an interested object (via @link powerStateWillChangeTo powerStateWillChangeTo@/link or @link powerStateDidChangeTo powerStateDidChangeTo@/link), the object can return an immediate acknowledgement via a return code, or it may return an indication that it will acknowledge later by calling <code>acknowledgePowerChange</code>.
1537 Interested objects are those that have registered as interested drivers, as well as power plane children of the power changing driver. A driver that calls @link registerInterestedDriver registerInterestedDriver@/link must call <code>acknowledgePowerChange</code>, or use an immediate acknowledgement return from <code>powerStateWillChangeTo</code> or <code>powerStateDidChangeTo</code>.
1538 @param whichDriver A pointer to the calling driver. The called object tracks all interested parties to ensure that all have acknowledged the power state change.
1539 @result <code>IOPMNoErr</code>. */
1540
1541 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1542 IOReturn acknowledgePowerChange( IOService * whichDriver );
1543
1544/*! @function acknowledgeSetPowerState
1545 @abstract Acknowledges the belated completion of a driver's <code>setPowerState</code> power state change.
1546 @discussion After power management instructs a driver to change its state via @link setPowerState setPowerState@/link, that driver must acknowledge the change when its device has completed its transition. The acknowledgement may be immediate, via a return code from <code>setPowerState</code>, or delayed, via this call to <code>acknowledgeSetPowerState</code>.
1547 Any driver that does not return <code>kIOPMAckImplied</code> from its <code>setPowerState</code> implementation must later call <code>acknowledgeSetPowerState</code>.
1548 @result <code>IOPMNoErr</code>. */
1549
1550 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1551 IOReturn acknowledgeSetPowerState( void );
1552
1553/*! @function requestPowerDomainState
1554 @abstract Tells a driver to adjust its power state.
1555 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1556
1557 virtual IOReturn requestPowerDomainState(
1558 IOPMPowerFlags desiredState,
1559 IOPowerConnection * whichChild,
1560 unsigned long specificationFlags );
1561
1562/*! @function makeUsable
1563 @abstract Requests that a device become usable.
1564 @discussion This method is called when some client of a device (or the device's own driver) is asking for the device to become usable. Power management responds by telling the object upon which this method is called to change to its highest power state.
1565 <code>makeUsable</code> is implemented using @link changePowerStateToPriv changePowerStateToPriv@/link. Subsequent requests for lower power, such as from <code>changePowerStateToPriv</code>, will pre-empt this request.
1566 @result A return code that can be ignored by the caller. */
1567
1568 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1569 IOReturn makeUsable( void );
1570
1571/*! @function temporaryPowerClampOn
1572 @abstract A driver calls this method to hold itself in the highest power state until it has children.
1573 @discussion Use <code>temporaryPowerClampOn</code> to hold your driver in its highest power state while waiting for child devices to attach. After children have attached, the clamp is released and the device's power state is controlled by the children's requirements.
1574 @result A return code that can be ignored by the caller. */
1575
1576 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1577 IOReturn temporaryPowerClampOn( void );
1578
1579/*! @function changePowerStateTo
1580 @abstract Sets a driver's power state.
1581 @discussion This function is one of several that are used to set a driver's power state. In most circumstances, however, you should call @link changePowerStateToPriv changePowerStateToPriv@/link instead.
1582 Calls to <code>changePowerStateTo</code>, <code>changePowerStateToPriv</code>, and a driver's power children all affect the power state of a driver. For legacy design reasons, they have overlapping functionality. Although you should call <code>changePowerStateToPriv</code> to change your device's power state, you might need to call <code>changePowerStateTo</code> in the following circumstances:
1583 <ul><li>If a driver will be using <code>changePowerStateToPriv</code> to change its power state, it should call <code>changePowerStateTo(0)</code> in its <code>start</code> routine to eliminate the influence <code>changePowerStateTo</code> has on power state calculations.
1584 <li>Call <code>changePowerStateTo</code> in conjunction with @link setIdleTimerPeriod setIdleTimerPeriod@/link and @link activityTickle activityTickle@/link to idle a driver into a low power state. For a driver with 3 power states, for example, <code>changePowerStateTo(1)</code> sets a minimum level of power state 1, such that the idle timer period may not set your device's power any lower than state 1.</ul>
1585 @param ordinal The number of the desired power state in the power state array.
1586 @result A return code that can be ignored by the caller. */
1587
1588 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1589 IOReturn changePowerStateTo( unsigned long ordinal );
1590
1591/*! @function currentCapability
1592 @abstract Finds out the capability of a device's current power state.
1593 @result A copy of the <code>capabilityFlags</code> field for the current power state in the power state array. */
1594
1595 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1596 IOPMPowerFlags currentCapability( void );
1597
1598/*! @function currentPowerConsumption
1599 @abstract Finds out the current power consumption of a device.
1600 @discussion Most Mac OS X power managed drivers do not report their power consumption via the <code>staticPower</code> field. Thus this call will not accurately reflect power consumption for most drivers.
1601 @result A copy of the <code>staticPower</code> field for the current power state in the power state array. */
1602
1603 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1604 unsigned long currentPowerConsumption( void );
1605
1606/*! @function activityTickle
1607 @abstract Informs power management when a power-managed device is in use, so that power management can track when it is idle and adjust its power state accordingly.
1608 @discussion The <code>activityTickle</code> method is provided for objects in the system (or for the driver itself) to tell a driver that its device is being used.
1609 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.
1610 After the device has been powered down by at least one power state, a subsequent call to <code>activityTickle</code> causes the device to be switched to a higher state required for the activity.
1611 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.
1612 @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.
1613 @param stateNumber When <code>type</code> is <code>kIOPMSuperclassPolicy1</code>, <code>stateNumber</code> contains the desired power state ordinal for the activity. If the device is in a lower state, the superclass will switch it to this state. This is for devices that can handle some accesses in lower power states; the device is powered up only as far as it needs to be for the activity.
1614 @result When <code>type</code> is <code>kIOPMSuperclassPolicy1</code>, the superclass returns <code>true</code> if the device is currently in the state specified by <code>stateNumber</code>. If the device is in a lower state and must be powered up, the superclass returns <code>false</code>; in this case the superclass will initiate a power change to power the device up. */
1615
1616 virtual bool activityTickle(
1617 unsigned long type,
1618 unsigned long stateNumber = 0 );
1619
1620/*! @function setAggressiveness
1621 @abstract Broadcasts an aggressiveness factor from the parent of a driver to the driver.
1622 @discussion Implement <code>setAggressiveness</code> to receive a notification when an "aggressiveness Aggressiveness factors are a loose set of power management variables that contain values for system sleep timeout, display sleep timeout, whether the system is on battery or AC, and other power management features. There are several aggressiveness factors that can be broadcast and a driver may take action on whichever factors apply to it.
1623 A driver that has joined the power plane via @link joinPMtree joinPMtree@/link will receive <code>setAgressiveness</code> calls when aggressiveness factors change.
1624 A driver may override this call if it needs to do something with the new factor (such as change its idle timeout). If overridden, the driver must call its superclass's <code>setAgressiveness</code> method in its own <code>setAgressiveness</code> implementation.
1625 Most drivers do not need to implement <code>setAgressiveness</code>.
1626 @param type The aggressiveness factor type, such as <code>kPMMinutesToDim</code>, <code>kPMMinutesToSpinDown</code>, <code>kPMMinutesToSleep</code>, and <code>kPMPowerSource</code>. (Aggressiveness factors are defined in <code>pwr_mgt/IOPM.h</code>.)
1627 @param newLevel The aggressiveness factor's new value.
1628 @result <code>IOPMNoErr</code>. */
1629
1630 virtual IOReturn setAggressiveness(
1631 unsigned long type,
1632 unsigned long newLevel );
1633
1634/*! @function getAggressiveness
1635 @abstract Returns the current aggressiveness value for the given type.
1636 @param type The aggressiveness factor to query.
1637 @param currentLevel Upon successful return, contains the value of aggressiveness factor <code>type</code>.
1638 @result <code>kIOReturnSuccess</code> upon success; an I/O Kit error code otherwise. */
1639
1640 virtual IOReturn getAggressiveness(
1641 unsigned long type,
1642 unsigned long * currentLevel );
1643
1644#ifndef __LP64__
1645/*! @function systemWake
1646 @abstract Tells every driver in the power plane that the system is waking up.
1647 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1648
1649 virtual IOReturn systemWake( void )
1650 APPLE_KEXT_DEPRECATED;
1651
1652/*! @function temperatureCriticalForZone
1653 @abstract Alerts a driver to a critical temperature in some thermal zone.
1654 @discussion This call is unused by power management. It is not intended to be called or overridden. */
1655
1656 virtual IOReturn temperatureCriticalForZone( IOService * whichZone )
1657 APPLE_KEXT_DEPRECATED;
1658
1659/*! @function youAreRoot
1660 @abstract Informs power management which IOService object is the power plane root.
1661 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1662
1663 virtual IOReturn youAreRoot( void )
1664 APPLE_KEXT_DEPRECATED;
1665
1666/*! @function setPowerParent
1667 @abstract This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1668
1669 virtual IOReturn setPowerParent(
1670 IOPowerConnection * parent,
1671 bool stateKnown,
1672 IOPMPowerFlags currentState )
1673 APPLE_KEXT_DEPRECATED;
1674#endif /* !__LP64__ */
1675
1676/*! @function addPowerChild
1677 @abstract Informs a driver that it has a new child.
1678 @discussion The Platform Expert uses this method to call a driver and introduce it to a new child. This call is handled internally by power management. It is not intended to be overridden or called by drivers.
1679 @param theChild A pointer to the child IOService object. */
1680
1681 virtual IOReturn addPowerChild( IOService * theChild );
1682
1683/*! @function removePowerChild
1684 @abstract Informs a power managed driver that one of its power plane childen is disappearing.
1685 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1686
1687 virtual IOReturn removePowerChild( IOPowerConnection * theChild );
1688
1689#ifndef __LP64__
1690/*! @function command_received
1691 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1692
1693 virtual void command_received( void *, void * , void * , void * );
1694#endif
1695
1696/*! @function start_PM_idle_timer
1697 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1698
1699 APPLE_KEXT_COMPATIBILITY_VIRTUAL
1700 void start_PM_idle_timer( void );
1701
1702#ifndef __LP64__
1703/*! @function PM_idle_timer_expiration
1704 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1705
1706 virtual void PM_idle_timer_expiration( void )
1707 APPLE_KEXT_DEPRECATED;
1708
1709/*! @function PM_Clamp_Timer_Expired
1710 @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */
1711
1712 virtual void PM_Clamp_Timer_Expired( void )
1713 APPLE_KEXT_DEPRECATED;
1714#endif
1715
1716/*! @function setIdleTimerPeriod
1717 @abstract Sets or changes the idle timer period.
1718 @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.
1719 @param period The desired idle timer period in seconds.
1720 @result <code>kIOReturnSuccess</code> upon success; an I/O Kit error code otherwise. */
1721
1722 virtual IOReturn setIdleTimerPeriod( unsigned long period );
1723
1724#ifndef __LP64__
1725/*! @function getPMworkloop
1726 @abstract Returns a pointer to the system-wide power management work loop.
1727 @availability Deprecated in Mac OS X version 10.6.
1728 @discussion Most drivers should create their own work loops to synchronize their code; drivers should not run arbitrary code on the power management work loop. */
1729
1730 virtual IOWorkLoop * getPMworkloop( void )
1731 APPLE_KEXT_DEPRECATED;
1732#endif
1733
1734/*! @function getPowerState
1735 @abstract Determines a device's power state.
1736 @discussion A device's "current power state" is updated at the end of each power state transition (e.g. transition from state 1 to state 0, or state 0 to state 2). This transition includes the time spent powering on or off any power plane children. Thus, if a child calls <code>getPowerState</code> on its power parent during system wake from sleep, the call will return the index to the device's off state rather than its on state.
1737 @result The current power state's index into the device's power state array. */
1738
1739 UInt32 getPowerState( void );
1740
1741/*! @function setPowerState
1742 @abstract Requests a power managed driver to change the power state of its device.
1743 @discussion A power managed driver must override <code>setPowerState</code> to take part in system power management. After a driver is registered with power management, the system uses <code>setPowerState</code> to power the device off and on for system sleep and wake.
1744 Calls to @link PMinit PMinit@/link and @link registerPowerDriver registerPowerDriver@/link enable power management to change a device's power state using <code>setPowerState</code>. <code>setPowerState</code> is called in a clean and separate thread context.
1745 @param powerStateOrdinal The number in the power state array of the state the driver is being instructed to switch to.
1746 @param whatDevice A pointer to the power management object which registered to manage power for this device. In most cases, <code>whatDevice</code> will be equal to your driver's own <code>this</code> pointer.
1747 @result The driver must return <code>IOPMAckImplied</code> if it has complied with the request when it returns. Otherwise if it has started the process of changing power state but not finished it, the driver should return a number of microseconds which is an upper limit of the time it will need to finish. Then, when it has completed the power switch, it should call @link acknowledgeSetPowerState acknowledgeSetPowerState@/link. */
1748
1749 virtual IOReturn setPowerState(
1750 unsigned long powerStateOrdinal,
1751 IOService * whatDevice );
1752
1753#ifndef __LP64__
1754/*! @function clampPowerOn
1755 @abstract Deprecated. Do not use. */
1756
1757 virtual void clampPowerOn( unsigned long duration );
1758#endif
1759
1760/*! @function maxCapabilityForDomainState
1761 @abstract Determines a driver's highest power state possible for a given power domain state.
1762 @discussion This happens when the power domain is changing state and power management needs to determine which state the device is capable of in the new domain state.
1763 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.
1764 @param domainState Flags that describe the character of "domain power"; they represent the <code>outputPowerCharacter</code> field of a state in the power domain's power state array.
1765 @result A state number. */
1766
1767 virtual unsigned long maxCapabilityForDomainState( IOPMPowerFlags domainState );
1768
1769/*! @function initialPowerStateForDomainState
1770 @abstract Determines which power state a device is in, given the current power domain state.
1771 @discussion Power management calls this method once, when the driver is initializing power management.
1772 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.
1773 @param domainState Flags that describe the character of "domain power"; they represent the <code>outputPowerCharacter</code> field of a state in the power domain's power state array.
1774 @result A state number. */
1775
1776 virtual unsigned long initialPowerStateForDomainState( IOPMPowerFlags domainState );
1777
1778/*! @function powerStateForDomainState
1779 @abstract Determines what power state the device would be in for a given power domain state.
1780 @discussion This call is unused by power management. Drivers should override <code>initialPowerStateForDomainState</code> and/or <code>maxCapabilityForDomainState</code> instead to change the default mapping of domain state to driver power state.
1781 @param domainState Flags that describe the character of "domain power"; they represent the <code>outputPowerCharacter</code> field of a state in the power domain's power state array.
1782 @result A state number. */
1783
1784 virtual unsigned long powerStateForDomainState( IOPMPowerFlags domainState );
1785
1786/*! @function powerStateWillChangeTo
1787 @abstract Informs interested parties that a device is about to change its power state.
1788 @discussion Power management informs interested parties that a device is about to change to a different power state. Interested parties are those that have registered for this notification via @link registerInterestedDriver registerInterestedDriver@/link. If you have called <code>registerInterestedDriver</code> on a power managed driver, you must implement <code>powerStateWillChangeTo</code> and @link powerStateDidChangeTo powerStateDidChangeTo@/link to receive the notifications.
1789 <code>powerStateWillChangeTo</code> is called in a clean and separate thread context. <code>powerStateWillChangeTo</code> is called before a power state transition takes place; <code>powerStateDidChangeTo</code> is called after the transition has completed.
1790 @param capabilities Flags that describe the capability of the device in the new power state (they come from the <code>capabilityFlags</code> field of the new state in the power state array).
1791 @param stateNumber The number of the state in the state array that the device is switching to.
1792 @param whatDevice A pointer to the driver that is changing. It can be used by a driver that is receiving power state change notifications for multiple devices to distinguish between them.
1793 @result The driver returns <code>IOPMAckImplied</code> 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 @link acknowledgePowerChange acknowledgePowerChange@/link. */
1794
1795 virtual IOReturn powerStateWillChangeTo(
1796 IOPMPowerFlags capabilities,
1797 unsigned long stateNumber,
1798 IOService * whatDevice );
1799
1800/*! @function powerStateDidChangeTo
1801 @abstract Informs interested parties that a device has changed to a different power state.
1802 @discussion Power management informs interested parties that a device has changed to a different power state. Interested parties are those that have registered for this notification via @link registerInterestedDriver registerInterestedDriver@/link. If you have called <code>registerInterestedDriver</code> on a power managed driver, you must implemnt @link powerStateWillChangeTo powerStateWillChangeTo@/link and <code>powerStateDidChangeTo</code> to receive the notifications.
1803 <code>powerStateDidChangeTo</code> is called in a clean and separate thread context. <code>powerStateWillChangeTo</code> is called before a power state transition takes place; <code>powerStateDidChangeTo</code> is called after the transition has completed.
1804 @param capabilities Flags that describe the capability of the device in the new power state (they come from the <code>capabilityFlags</code> field of the new state in the power state array).
1805 @param stateNumber The number of the state in the state array that the device is switching to.
1806 @param whatDevice A pointer to the driver that is changing. It can be used by a driver that is receiving power state change notifications for multiple devices to distinguish between them.
1807 @result The driver returns <code>IOPMAckImplied</code> 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 @link acknowledgePowerChange acknowledgePowerChange@/link. */
1808
1809 virtual IOReturn powerStateDidChangeTo(
1810 IOPMPowerFlags capabilities,
1811 unsigned long stateNumber,
1812 IOService * whatDevice );
1813
1814#ifndef __LP64__
1815/*! @function didYouWakeSystem
1816 @abstract Asks a driver if its device is the one that just woke the system from sleep.
1817 @availability Deprecated in Mac OS X version 10.6.
1818 @discussion Power management calls a power managed driver with this method to ask if its device is the one that just woke the system from sleep. If a device is capable of waking the system from sleep, its driver should implement <code>didYouWakeSystem</code> and return <code>true</code> if its device was responsible for waking the system.
1819 @result <code>true</code> if the driver's device woke the system and <code>false</code> otherwise. */
1820
1821 virtual bool didYouWakeSystem( void )
1822 APPLE_KEXT_DEPRECATED;
1823
1824/*! @function newTemperature
1825 @abstract Tells a power managed driver that the temperature in the thermal zone has changed.
1826 @discussion This call is unused by power management. It is not intended to be called or overridden. */
1827
1828 virtual IOReturn newTemperature( long currentTemp, IOService * whichZone )
1829 APPLE_KEXT_DEPRECATED;
1830#endif
1831
1832 virtual bool askChangeDown( unsigned long );
1833 virtual bool tellChangeDown( unsigned long );
1834 virtual void tellNoChangeDown ( unsigned long );
1835 virtual void tellChangeUp( unsigned long );
1836 virtual IOReturn allowPowerChange( unsigned long refcon );
1837 virtual IOReturn cancelPowerChange( unsigned long refcon );
1838
1839protected:
1840/*! @function changePowerStateToPriv
1841 @abstract Tells a driver's superclass to change the power state of its device.
1842 @discussion A driver uses this method to tell its superclass to change the power state of the device. This is the recommended way to change the power state of a device.
1843 Three things affect driver power state: @link changePowerStateTo changePowerStateTo@/link, <code>changePowerStateToPriv</code>, and the desires of the driver's power plane children. Power management puts the device into the maximum state governed by those three entities.
1844 Drivers may eliminate the influence of the <code>changePowerStateTo</code> method on power state one of two ways. See @link powerOverrideOnPriv powerOverrideOnPriv@/link to ignore the method's influence, or call <code>changePowerStateTo(0)</code> in the driver's <code>start</code> routine to remove the <code>changePowerStateTo</code> method's power request.
1845 @param ordinal The number of the desired power state in the power state array.
1846 @result A return code that can be ignored by the caller. */
1847
1848 IOReturn changePowerStateToPriv( unsigned long ordinal );
1849
1850/*! @function powerOverrideOnPriv
1851 @abstract Allows a driver to ignore its children's power management requests and only use changePowerStateToPriv to define its own power state.
1852 @discussion Power management normally keeps a device at the highest state required by its requests via @link changePowerStateTo changePowerStateTo@/link, @link changePowerStateToPriv changePowerStateToPriv@/link, and its children. However, a driver may ensure a lower power state than otherwise required by itself and its children using <code>powerOverrideOnPriv</code>. When the override is on, power management keeps the device's power state in the state specified by <code>changePowerStateToPriv</code>. Turning on the override will initiate a power change if the driver's <code>changePowerStateToPriv</code> desired power state is different from the maximum of the <code>changePowerStateTo</code> desired power state and the children's desires.
1853 @result A return code that can be ignored by the caller. */
1854
1855 IOReturn powerOverrideOnPriv( void );
1856
1857/*! @function powerOverrideOffPriv
1858 @abstract Allows a driver to disable a power override.
1859 @discussion When a driver has enabled an override via @link powerOverrideOnPriv powerOverrideOnPriv@/link, it can disable it again by calling this method in its superclass. Disabling the override reverts to the default algorithm for determining a device's power state. The superclass will now keep the device at the highest state required by <code>changePowerStateTo</code>, <code>changePowerStateToPriv</code>, and its children. Turning off the override will initiate a power change if the driver's desired power state is different from the maximum of the power managed driver's desire and the children's desires.
1860 @result A return code that can be ignored by the caller. */
1861
1862 IOReturn powerOverrideOffPriv( void );
1863
1864/*! @function powerChangeDone
1865 @abstract Tells a driver when a power state change is complete.
1866 @discussion Power management uses this method to inform a driver when a power change is completely done, when all interested parties have acknowledged the @link powerStateDidChangeTo powerStateDidChangeTo@/link call. The default implementation of this method is null; the method is meant to be overridden by subclassed power managed drivers. A driver should use this method to find out if a power change it initiated is complete.
1867 @param stateNumber The number of the state in the state array that the device has switched from. */
1868
1869 virtual void powerChangeDone( unsigned long stateNumber );
1870#ifdef XNU_KERNEL_PRIVATE
1871 /* Power management internals */
1872public:
1873 void idleTimerExpired( void );
1874 void settleTimerExpired( void );
1875 IOReturn synchronizePowerTree( IOOptionBits options = 0, IOService * notifyRoot = 0 );
1876 bool assertPMDriverCall( IOPMDriverCallEntry * callEntry, IOOptionBits options = 0, IOPMinformee * inform = 0 );
1877 void deassertPMDriverCall( IOPMDriverCallEntry * callEntry );
1878 IOReturn changePowerStateWithOverrideTo( IOPMPowerStateIndex ordinal, IOPMRequestTag tag );
1879 IOReturn changePowerStateForRootDomain( IOPMPowerStateIndex ordinal );
1880 IOReturn setIgnoreIdleTimer( bool ignore );
1881 IOReturn quiescePowerTree( void * target, IOPMCompletionAction action, void * param );
1882 uint32_t getPowerStateForClient( const OSSymbol * client );
1883 static const char * getIOMessageString( uint32_t msg );
1884 static void setAdvisoryTickleEnable( bool enable );
1885 void reset_watchdog_timer(IOService *obj, int timeout);
1886 void start_watchdog_timer ( void );
1887 void stop_watchdog_timer ( void );
1888 void start_watchdog_timer(uint64_t deadline);
1889 IOReturn registerInterestForNotifier( IONotifier *notify, const OSSymbol * typeOfInterest,
1890 IOServiceInterestHandler handler, void * target, void * ref );
1891
1892 static IOWorkLoop * getIOPMWorkloop( void );
1893 bool getBlockingDriverCall(thread_t *thread, const void **callMethod);
1894
1895protected:
1896 bool tellClientsWithResponse( int messageType );
1897 void tellClients( int messageType );
1898 void PMDebug( uint32_t event, uintptr_t param1, uintptr_t param2 );
1899
1900private:
1901#ifndef __LP64__
1902 void ack_timer_ticked ( void );
1903 IOReturn serializedAllowPowerChange2 ( unsigned long );
1904 IOReturn serializedCancelPowerChange2 ( unsigned long );
1905 IOReturn powerDomainWillChangeTo( IOPMPowerFlags, IOPowerConnection * );
1906 IOReturn powerDomainDidChangeTo( IOPMPowerFlags, IOPowerConnection * );
1907#endif
1908 void PMfree( void );
1909 bool tellChangeDown1 ( unsigned long );
1910 bool tellChangeDown2 ( unsigned long );
1911 IOReturn startPowerChange( IOPMPowerChangeFlags, IOPMPowerStateIndex, IOPMPowerFlags, IOPowerConnection *, IOPMPowerFlags );
1912 void setParentInfo ( IOPMPowerFlags, IOPowerConnection *, bool );
1913 IOReturn notifyAll ( uint32_t nextMS );
1914 bool notifyChild ( IOPowerConnection * child );
1915 IOPMPowerStateIndex getPowerStateForDomainFlags( IOPMPowerFlags flags );
1916
1917 // power change initiated by driver
1918 void OurChangeStart( void );
1919 void OurSyncStart ( void );
1920 void OurChangeTellClientsPowerDown ( void );
1921 void OurChangeTellUserPMPolicyPowerDown ( void );
1922 void OurChangeTellPriorityClientsPowerDown ( void );
1923 void OurChangeTellCapabilityWillChange ( void );
1924 void OurChangeNotifyInterestedDriversWillChange ( void );
1925 void OurChangeSetPowerState ( void );
1926 void OurChangeWaitForPowerSettle ( void );
1927 void OurChangeNotifyInterestedDriversDidChange ( void );
1928 void OurChangeTellCapabilityDidChange ( void );
1929 void OurChangeFinish ( void );
1930
1931 // downward power change initiated by a power parent
1932 IOReturn ParentChangeStart( void );
1933 void ParentChangeTellPriorityClientsPowerDown ( void );
1934 void ParentChangeTellCapabilityWillChange ( void );
1935 void ParentChangeNotifyInterestedDriversWillChange ( void );
1936 void ParentChangeSetPowerState ( void );
1937 void ParentChangeWaitForPowerSettle ( void );
1938 void ParentChangeNotifyInterestedDriversDidChange ( void );
1939 void ParentChangeTellCapabilityDidChange ( void );
1940 void ParentChangeAcknowledgePowerChange ( void );
1941 void ParentChangeRootChangeDown( void );
1942
1943 void all_done ( void );
1944 void start_ack_timer ( void );
1945 void stop_ack_timer ( void );
1946 void start_ack_timer( UInt32 value, UInt32 scale );
1947 void startSettleTimer( void );
1948 void start_spindump_timer( const char * delay_type );
1949 void stop_spindump_timer( void );
1950 bool checkForDone ( void );
1951 bool responseValid ( uint32_t x, int pid );
1952 void computeDesiredState( unsigned long tempDesire, bool computeOnly );
1953 void trackSystemSleepPreventers( IOPMPowerStateIndex, IOPMPowerStateIndex, IOPMPowerChangeFlags );
1954 void tellSystemCapabilityChange( uint32_t nextMS );
1955 void restartIdleTimer( void );
1956
1957 static void ack_timer_expired( thread_call_param_t, thread_call_param_t );
1958 static void watchdog_timer_expired ( thread_call_param_t arg0, thread_call_param_t arg1 );
1959 static void spindump_timer_expired( thread_call_param_t arg0, thread_call_param_t arg1 );
1960 static IOReturn actionAckTimerExpired(OSObject *, void *, void *, void *, void * );
1961 static IOReturn actionSpinDumpTimerExpired(OSObject *, void *, void *, void *, void * );
1962
1963 static IOReturn actionDriverCalloutDone(OSObject *, void *, void *, void *, void * );
1964 static IOPMRequest * acquirePMRequest( IOService * target, IOOptionBits type, IOPMRequest * active = 0 );
1965 static void releasePMRequest( IOPMRequest * request );
1966 static void pmDriverCallout( IOService * from );
1967 static void pmTellAppWithResponse( OSObject * object, void * context );
1968 static void pmTellClientWithResponse( OSObject * object, void * context );
1969 static void pmTellCapabilityAppWithResponse ( OSObject * object, void * arg );
1970 static void pmTellCapabilityClientWithResponse( OSObject * object, void * arg );
1971 static void submitPMRequest( IOPMRequest * request );
1972 static void submitPMRequests( IOPMRequest ** request, IOItemCount count );
1973 bool ackTimerTick( void );
1974 void addPowerChild1( IOPMRequest * request );
1975 void addPowerChild2( IOPMRequest * request );
1976 void addPowerChild3( IOPMRequest * request );
1977 void adjustPowerState( uint32_t clamp = 0 );
1978 void handlePMstop( IOPMRequest * request );
1979 void handleRegisterPowerDriver( IOPMRequest * request );
1980 bool handleAcknowledgePowerChange( IOPMRequest * request );
1981 void handlePowerDomainWillChangeTo( IOPMRequest * request );
1982 void handlePowerDomainDidChangeTo( IOPMRequest * request );
1983 void handleRequestPowerState( IOPMRequest * request );
1984 void handlePowerOverrideChanged( IOPMRequest * request );
1985 void handleActivityTickle( IOPMRequest * request );
1986 void handleInterestChanged( IOPMRequest * request );
1987 void handleSynchronizePowerTree( IOPMRequest * request );
1988 void executePMRequest( IOPMRequest * request );
1989 bool actionPMWorkQueueInvoke( IOPMRequest * request, IOPMWorkQueue * queue );
1990 bool actionPMWorkQueueRetire( IOPMRequest * request, IOPMWorkQueue * queue );
1991 bool actionPMRequestQueue( IOPMRequest * request, IOPMRequestQueue * queue );
1992 bool actionPMReplyQueue( IOPMRequest * request, IOPMRequestQueue * queue );
1993 bool actionPMCompletionQueue( IOPMRequest * request, IOPMCompletionQueue * queue );
1994 bool notifyInterestedDrivers( void );
1995 void notifyInterestedDriversDone( void );
1996 bool notifyControllingDriver( void );
1997 void notifyControllingDriverDone( void );
1998 void driverSetPowerState( void );
1999 void driverInformPowerChange( void );
2000 bool isPMBlocked( IOPMRequest * request, int count );
2001 void notifyChildren( void );
2002 void notifyChildrenOrdered( void );
2003 void notifyChildrenDelayed( void );
2004 void notifyRootDomain( void );
2005 void notifyRootDomainDone( void );
2006 void cleanClientResponses ( bool logErrors );
2007 void updatePowerClient( const OSSymbol * client, uint32_t powerState );
2008 void removePowerClient( const OSSymbol * client );
2009 IOReturn requestPowerState( const OSSymbol * client, uint32_t state );
2010 IOReturn requestDomainPower( IOPMPowerStateIndex ourPowerState, IOOptionBits options = 0 );
2011 IOReturn configurePowerStatesReport( IOReportConfigureAction action, void *result );
2012 IOReturn updatePowerStatesReport( IOReportConfigureAction action, void *result, void *destination );
2013 IOReturn configureSimplePowerReport(IOReportConfigureAction action, void *result );
2014 IOReturn updateSimplePowerReport( IOReportConfigureAction action, void *result, void *destination );
2015 void waitForPMDriverCall( IOService * target = 0 );
2016#endif /* XNU_KERNEL_PRIVATE */
2017};
2018
2019#endif /* ! _IOKIT_IOSERVICE_H */
2020