1 /* 2 * Copyright (c) 1998-2020 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 #include <DriverKit/IOService.h> 57 #include <libkern/c++/OSPtr.h> 58 59 #if __cplusplus >= 201703L 60 extern "C++" { 61 #include <libkern/c++/OSSharedPtr.h> 62 } 63 #endif 64 65 extern "C" { 66 #include <kern/thread_call.h> 67 } 68 69 70 #ifndef UINT64_MAX 71 #define UINT64_MAX 18446744073709551615ULL 72 #endif 73 74 75 enum { 76 kIODefaultProbeScore = 0 77 }; 78 79 // masks for getState() 80 enum { 81 kIOServiceInactiveState = 0x00000001, 82 kIOServiceRegisteredState = 0x00000002, 83 kIOServiceMatchedState = 0x00000004, 84 kIOServiceFirstPublishState = 0x00000008, 85 kIOServiceFirstMatchState = 0x00000010, 86 kIOServiceReservedMatchState = 0x80000000, 87 #if XNU_KERNEL_PRIVATE 88 kIOServiceUserInvisibleMatchState = kIOServiceReservedMatchState, 89 #endif /* XNU_KERNEL_PRIVATE */ 90 }; 91 92 enum { 93 // options for registerService() 94 kIOServiceExclusive = 0x00000001, 95 96 // options for terminate() 97 kIOServiceRequired = 0x00000001, 98 kIOServiceTerminate = 0x00000004, 99 kIOServiceTerminateWithRematch = 0x00000010, 100 kIOServiceTerminateWithRematchCurrentDext = 0x00000020, 101 102 // options for registerService() & terminate() 103 kIOServiceSynchronous = 0x00000002, 104 // options for registerService() 105 kIOServiceAsynchronous = 0x00000008, 106 kIOServiceDextRequirePowerForMatching = 0x00000010, 107 }; 108 109 // options for open() 110 enum { 111 kIOServiceSeize = 0x00000001, 112 kIOServiceFamilyOpenOptions = 0xffff0000 113 }; 114 115 // options for close() 116 enum { 117 kIOServiceFamilyCloseOptions = 0xffff0000 118 }; 119 120 typedef void * IONotificationRef; 121 122 extern const IORegistryPlane * gIOServicePlane; 123 extern const IORegistryPlane * gIOPowerPlane; 124 125 extern const OSSymbol * gIOResourcesKey; 126 extern const OSSymbol * gIOResourceMatchKey; 127 extern const OSSymbol * gIOResourceMatchedKey; 128 extern const OSSymbol * gIOResourceIOKitKey; 129 130 extern const OSSymbol * gIOProviderClassKey; 131 extern const OSSymbol * gIONameMatchKey; 132 extern const OSSymbol * gIONameMatchedKey; 133 extern const OSSymbol * gIOPropertyMatchKey; 134 extern const OSSymbol * gIOPropertyExistsMatchKey; 135 extern const OSSymbol * gIOLocationMatchKey; 136 extern const OSSymbol * gIOParentMatchKey; 137 extern const OSSymbol * gIOPathMatchKey; 138 extern const OSSymbol * gIOMatchCategoryKey; 139 extern const OSSymbol * gIODefaultMatchCategoryKey; 140 extern const OSSymbol * gIOMatchedServiceCountKey; 141 extern const OSSymbol * gIOMatchedPersonalityKey; 142 extern const OSSymbol * gIORematchPersonalityKey; 143 extern const OSSymbol * gIORematchCountKey; 144 extern const OSSymbol * gIODEXTMatchCountKey; 145 146 extern const OSSymbol * gIOUserClientClassKey; 147 148 extern const OSSymbol * gIOUserClassKey; 149 extern const OSSymbol * gIOUserClassesKey; 150 extern const OSSymbol * gIOUserServerClassKey; 151 extern const OSSymbol * gIOUserServerNameKey; 152 extern const OSSymbol * gIOUserServerTagKey; 153 extern const OSSymbol * gIOUserUserClientKey; 154 extern const OSSymbol * gIOAssociatedServicesKey; 155 extern const OSSymbol * gIOUserServerPreserveUserspaceRebootKey; 156 157 extern const OSSymbol * gIOKitDebugKey; 158 extern const OSSymbol * gIOServiceKey; 159 160 extern const OSSymbol * gIOCommandPoolSizeKey; 161 162 extern const OSSymbol * gIOPublishNotification; 163 extern const OSSymbol * gIOFirstPublishNotification; 164 extern const OSSymbol * gIOMatchedNotification; 165 extern const OSSymbol * gIOFirstMatchNotification; 166 extern const OSSymbol * gIOTerminatedNotification; 167 extern const OSSymbol * gIOWillTerminateNotification; 168 169 extern const OSSymbol * gIOGeneralInterest; 170 extern const OSSymbol * gIOBusyInterest; 171 extern const OSSymbol * gIOOpenInterest; 172 extern const OSSymbol * gIOAppPowerStateInterest; 173 extern const OSSymbol * gIOPriorityPowerStateInterest; 174 extern const OSSymbol * gIOConsoleSecurityInterest; 175 176 extern const OSSymbol * gIODeviceMemoryKey; 177 extern const OSSymbol * gIOInterruptControllersKey; 178 extern const OSSymbol * gIOInterruptSpecifiersKey; 179 180 extern const OSSymbol * gIOSupportedPropertiesKey; 181 extern const OSSymbol * gIOUserServicePropertiesKey; 182 extern const OSSymbol * gIOCompatibilityMatchKey; 183 extern const OSSymbol * gIOCompatibilityPropertiesKey; 184 extern const OSSymbol * gIOPathKey; 185 186 extern const OSSymbol * gIOBSDKey; 187 extern const OSSymbol * gIOBSDNameKey; 188 extern const OSSymbol * gIOBSDMajorKey; 189 extern const OSSymbol * gIOBSDMinorKey; 190 extern const OSSymbol * gIOBSDUnitKey; 191 192 extern const OSSymbol * gIOUserClientEntitlementsKey; 193 extern const OSSymbol * gIODriverKitEntitlementKey; 194 extern const OSSymbol * gIOServiceDEXTEntitlementsKey; 195 extern const OSSymbol * gIODriverKitUserClientEntitlementsKey; 196 extern const OSSymbol * gIODriverKitUserClientEntitlementAllowAnyKey; 197 extern const OSSymbol * gIODriverKitRequiredEntitlementsKey; 198 extern const OSSymbol * gIODriverKitTestDriverEntitlementKey; 199 extern const OSSymbol * gIODriverKitUserClientEntitlementCommunicatesWithDriversKey; 200 extern const OSSymbol * gIODriverKitUserClientEntitlementAllowThirdPartyUserClientsKey; 201 extern const OSSymbol * gIOMatchDeferKey; 202 extern const OSSymbol * gIOExclaveAssignedKey; 203 204 extern const OSSymbol * gIOAllCPUInitializedKey; 205 206 #if XNU_KERNEL_PRIVATE && !defined(IOServiceTrace) 207 208 #include <IOKit/IOTimeStamp.h> 209 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) 210 #define IOServiceTrace(csc, a, b, c, d) do { \ 211 if(kIOTraceIOService & gIOKitTrace) { \ 212 KERNEL_DEBUG_CONSTANT(IODBG_IOSERVICE(csc), a, b, c, d, 0); \ 213 } \ 214 } while(0) 215 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */ 216 #define IOServiceTrace(csc, a, b, c, d) do { \ 217 (void)a; \ 218 (void)b; \ 219 (void)c; \ 220 (void)d; \ 221 } while (0) 222 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */ 223 224 #endif // XNU_KERNEL_PRIVATE && !IOServiceTrace 225 226 extern SInt32 IOServiceOrdering( const OSMetaClassBase * inObj1, const OSMetaClassBase * inObj2, void * ref ); 227 228 typedef void (*IOInterruptAction)( OSObject * target, void * refCon, 229 IOService * nub, int source ); 230 231 #ifdef __BLOCKS__ 232 typedef void (^IOInterruptActionBlock)(IOService * nub, int source); 233 typedef kern_return_t (^IOStateNotificationHandler)(void); 234 #ifdef KERNEL_PRIVATE 235 typedef bool (^ANEUpcallSetPowerStateHandler)(uint32_t desiredState); 236 typedef bool (^ANEUpcallWorkHandler)(uint64_t arg0, uint64_t arg1, uint64_t arg2); 237 #endif 238 #endif /* __BLOCKS__ */ 239 240 typedef void * IOStateNotificationListenerRef; 241 class IOStateNotificationItem; 242 243 /*! @typedef IOServiceNotificationHandler 244 * @param target Reference supplied when the notification was registered. 245 * @param refCon Reference constant supplied when the notification was registered. 246 * @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. */ 247 248 typedef bool (*IOServiceNotificationHandler)( void * target, void * refCon, 249 IOService * newService ); 250 251 typedef bool (*IOServiceMatchingNotificationHandler)( void * target, void * refCon, 252 IOService * newService, 253 IONotifier * notifier ); 254 255 #ifdef __BLOCKS__ 256 typedef bool (^IOServiceMatchingNotificationHandlerBlock)(IOService * newService, 257 IONotifier * notifier ); 258 #endif /* __BLOCKS__ */ 259 260 261 /*! @typedef IOServiceInterestHandler 262 * @param target Reference supplied when the notification was registered. 263 * @param refCon Reference constant supplied when the notification was registered. 264 * @param messageType Type of the message - IOKit defined in IOKit/IOMessage.h or family specific. 265 * @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. 266 * @param messageArgument An argument for message, dependent on its type. 267 * @param argSize Non zero if the argument represents a struct of that size, used when delivering messages outside the kernel. */ 268 269 typedef IOReturn (*IOServiceInterestHandler)( void * target, void * refCon, 270 UInt32 messageType, IOService * provider, 271 void * messageArgument, vm_size_t argSize ); 272 273 #ifdef __BLOCKS__ 274 typedef IOReturn (^IOServiceInterestHandlerBlock)( uint32_t messageType, IOService * provider, 275 void * messageArgument, size_t argSize ); 276 #endif /* __BLOCKS__ */ 277 278 typedef void (*IOServiceApplierFunction)(IOService * service, void * context); 279 typedef void (*OSObjectApplierFunction)(OSObject * object, void * context); 280 #ifdef __BLOCKS__ 281 typedef void (^IOServiceApplierBlock)(IOService * service); 282 typedef void (^OSObjectApplierBlock)(OSObject * object); 283 #endif /* __BLOCKS__ */ 284 285 286 class IOUserClient; 287 class IOPlatformExpert; 288 class IOUserServerCheckInToken; 289 class IOInterruptEventSource; 290 291 /*! @class IOService 292 * @abstract The base class for most I/O Kit families, devices, and drivers. 293 * @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. 294 * 295 * Types of service are specified with a matching dictionary that describes properties of the service. For example, a matching dictionary might describe any IOUSBDevice (or subclass), an IOUSBDevice with a certain class code, or a IOPCIDevice with a set of matching names or device & vendor IDs. Since the matching dictionary is interpreted by the family which created the service, as well as generically by IOService, the list of properties considered for matching depends on the familiy. 296 * 297 * Matching dictionaries are associated with IOService classes by the catalogue, as driver property tables, and also supplied by clients of the notification APIs. 298 * 299 * IOService provides matching based on C++ class (via OSMetaClass dynamic casting), registry entry name, a registry path to the service (which includes device tree paths), a name assigned by BSD, or by its location (its point of attachment). 300 * 301 * <br><br>Driver Instantiation by IOService<br><br> 302 * 303 * Drivers are subclasses of IOService, and their availability is managed through the catalogue. They are instantiated based on the publication of an IOService they use (for example, an IOPCIDevice or IOUSBDevice), or when they are added to the catalogue and the IOService(s) they use are already available. 304 * 305 * When an IOService (the "provider") is published with the @link registerService registerService@/link method, the matching and probing process begins, which is always single threaded per provider. A list of matching dictionaries from the catalog and installed publish notification requests, that successfully match the IOService, is constructed, with ordering supplied by <code>kIOProbeScoreKey</code> ("IOProbeScore") property in the dictionary, or supplied with the notification. 306 * 307 * Each entry in the list is then processed in order - for notifications, the notification is delivered, for driver property tables a lot more happens. 308 * 309 * The 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). 310 * 311 * When 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. 312 * 313 * For 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. 314 * 315 * The driver should only consider itself in action when the start method is called, meaning it has been selected for use on the provider, and consuming that particular match category. It should also be prepared to be allocated, probed and freed even if the probe was successful. 316 * 317 * After the drivers have all synchronously been started, the installed "matched" notifications that match the registered IOService are delivered. 318 * 319 * <br><br>Properties used by IOService<br><br> 320 * 321 * <code>kIOClassKey, extern const OSSymbol * gIOClassKey, "IOClass"</code> 322 * <br> 323 * <br> 324 * Class of the driver to instantiate on matching providers. 325 * <br> 326 * <br> 327 * <code>kIOProviderClassKey, extern const OSSymbol * gIOProviderClassKey, "IOProviderClass"</code> 328 * <br> 329 * <br> 330 * Class of the provider(s) to be considered for matching, checked with OSDynamicCast so subclasses will also match. 331 * <br> 332 * <br> 333 * <code>kIOProbeScoreKey, extern const OSSymbol * gIOProbeScoreKey, "IOProbeScore"</code> 334 * <br> 335 * <br> 336 * The probe score initially used to order multiple matching drivers. 337 * <br> 338 * <br> 339 * <code>kIOMatchCategoryKey, extern const OSSymbol * gIOMatchCategoryKey, "IOMatchCategory"</code> 340 * <br> 341 * <br> 342 * A 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. 343 * <br> 344 * <br> 345 * <code>kIONameMatchKey, extern const OSSymbol * gIONameMatchKey, "IONameMatch"</code> 346 * <br> 347 * A string or collection of strings that match the provider's name. The comparison is implemented with the @link //apple_ref/cpp/instm/IORegistryEntry/compareNames/virtualbool/(OSObject*,OSString**) IORegistryEntry::compareNames@/link method, which supports a single string, or any collection (OSArray, OSSet, OSDictionary etc.) of strings. IOService objects with 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. 348 * <br> 349 * Examples 350 * <pre> 351 * @textblock 352 * <key>IONameMatch</key> 353 * <string>pci106b,7</string> 354 * @/textblock 355 * </pre> 356 * 357 * For a list of possible matching names, a serialized array of strings should used, eg. 358 * <pre> 359 * @textblock 360 * <key>IONameMatch</key> 361 * <array> 362 * <string>APPL,happy16</string> 363 * <string>pci106b,7</string> 364 * </array> 365 * @/textblock 366 * </pre> 367 * 368 * <br> 369 * <code>kIONameMatchedKey, extern const OSSymbol * gIONameMatchedKey, "IONameMatched"</code> 370 * <br> 371 * The 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. 372 * <br> 373 * <br> 374 * <code>kIOPropertyMatchKey, extern const OSSymbol * gIOPropertyMatchKey, "IOPropertyMatch"</code> 375 * <br> 376 * A dictionary of properties that each must exist in the matching IOService and compare successfully with the <code>isEqualTo</code> method. 377 * 378 * <pre> 379 * @textblock 380 * <key>IOPropertyMatch</key> 381 * <dictionary> 382 * <key>APPL,happy16</key> 383 * <string>APPL,meek8</string> 384 * </dictionary> 385 * @/textblock 386 * </pre> 387 * 388 * <br> 389 * <code>kIOUserClientClassKey, extern const OSSymbol * gIOUserClientClassKey, "IOUserClientClass"</code> 390 * <br> 391 * The class name that the service will attempt to allocate when a user client connection is requested. First the device nub is queried, then the nub's provider is queried by default. 392 * <br> 393 * <br> 394 * <code>kIOKitDebugKey, extern const OSSymbol * gIOKitDebugKey, "IOKitDebug"</code> 395 * <br> 396 * Set some debug flags for logging the driver loading process. Flags are defined in <code>IOKit/IOKitDebug.h</code>, but <code>65535</code> works well.*/ 397 398 struct IOInterruptAccountingData; 399 struct IOInterruptAccountingReporter; 400 struct OSObjectUserVars; 401 struct IOServiceStateChangeVars; 402 struct IOInterruptSourcePrivate; 403 404 class IOService : public IORegistryEntry 405 { 406 OSDeclareDefaultStructorsWithDispatch(IOService); 407 408 #if XNU_KERNEL_PRIVATE 409 public: 410 #else 411 protected: 412 #endif /* XNU_KERNEL_PRIVATE */ 413 /*! @struct ExpansionData 414 * @discussion This structure will be used to expand the capablilties of this class in the future. 415 */ 416 #if XNU_KERNEL_PRIVATE 417 struct ExpansionData { 418 uint64_t authorizationID; 419 /* 420 * Variables associated with interrupt accounting. Consists of an array 421 * (that pairs reporters with opaque "statistics" objects), the count for 422 * the array, and a lock to guard both of the former variables. The lock 423 * is necessary as IOReporting will not update reports in a manner that is 424 * synchonized with the service (i.e, on a workloop). 425 */ 426 IOLock interruptStatisticsLock; 427 IOInterruptAccountingReporter * interruptStatisticsArray; 428 int interruptStatisticsArrayCount; 429 430 OSObjectUserVars * uvars; 431 IOServiceStateChangeVars * svars; 432 433 IOInterruptSourcePrivate * interruptSourcesPrivate; 434 }; 435 #else 436 struct ExpansionData; 437 #endif 438 439 /*! @var reserved 440 * Reserved for future use. (Internal use only) */ 441 APPLE_KEXT_WSHADOW_PUSH; 442 ExpansionData * reserved; 443 APPLE_KEXT_WSHADOW_POP; 444 445 private: 446 IOService * __provider; 447 SInt32 __providerGeneration; 448 #if XNU_KERNEL_PRIVATE 449 uint32_t __resv1; 450 #endif 451 IOService * __owner; 452 IOOptionBits __state[2]; 453 uint64_t __timeBusy; 454 uint64_t __accumBusy; 455 IOServicePM * pwrMgt; 456 457 protected: 458 // TRUE once PMinit has been called 459 bool initialized; 460 #if XNU_KERNEL_PRIVATE 461 bool __machPortHoldDestroy; 462 uint8_t __resv2[6]; 463 #endif /* XNU_KERNEL_PRIVATE */ 464 465 public: 466 // DEPRECATED 467 void * pm_vars; 468 469 public: 470 /* methods available in Mac OS X 10.1 or later */ 471 /*! @function requestTerminate 472 * @abstract Passes a termination up the stack. 473 * @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. 474 * @param provider The terminated provider of this object. 475 * @param options Options originally passed to terminate, plus <code>kIOServiceRecursing</code>. 476 * @result <code>true</code> if this object should be terminated now that its provider has been. */ 477 478 virtual bool requestTerminate( IOService * provider, IOOptionBits options ); 479 480 /*! @function willTerminate 481 * @abstract Passes a termination up the stack. 482 * @discussion Notification that a provider has been terminated, sent before recursing up the stack, in root-to-leaf order. 483 * @param provider The terminated provider of this object. 484 * @param options Options originally passed to terminate. 485 * @result <code>true</code>. */ 486 487 virtual bool willTerminate( IOService * provider, IOOptionBits options ); 488 489 /*! @function didTerminate 490 * @abstract Passes a termination up the stack. 491 * @discussion Notification that a provider has been terminated, sent after recursing up the stack, in leaf-to-root order. 492 * @param provider The terminated provider of this object. 493 * @param options Options originally passed to terminate. 494 * @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>. 495 * @result <code>true</code>. */ 496 497 virtual bool didTerminate( IOService * provider, IOOptionBits options, bool * defer ); 498 499 /*! @function nextIdleTimeout 500 * @availability Mac OS X v10.4 and later 501 * @abstract Allows subclasses to customize idle power management behavior. 502 * @discussion Returns the next time that the device should idle into its next lower power state. Subclasses may override for custom idle behavior. 503 * 504 * A power managed driver might override this method to provide a more sophisticated idle power off algorithm than the one defined by power management. 505 * @param currentTime The current time 506 * @param lastActivity The time of last activity on this device 507 * @param powerState The device's current power state. 508 * @result Returns the next time the device should idle off (in seconds, relative to the current time). */ 509 510 virtual SInt32 nextIdleTimeout(AbsoluteTime currentTime, 511 AbsoluteTime lastActivity, unsigned int powerState); 512 513 /*! @function systemWillShutdown 514 * @availability Mac OS X v10.5 and later 515 * @abstract Notifies members of the power plane of system shutdown and restart. 516 * @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. 517 * 518 * 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. 519 * @param specifier <code>kIOMessageSystemWillPowerOff</code> or <code>kIOMessageSystemWillRestart</code>. */ 520 521 virtual void systemWillShutdown( IOOptionBits specifier ); 522 523 /*! @function copyClientWithCategory 524 * @availability Mac OS X v10.6 and later 525 * @param category An OSSymbol corresponding to an IOMatchCategory matching property. 526 * @result Returns a reference to the IOService child with the given category. The result should be released by the caller. 527 */ 528 529 virtual IOService * copyClientWithCategory( const OSSymbol * category ); 530 531 public: 532 /*! @function configureReport 533 * @abstract configure IOReporting channels 534 * @availability SPI on OS X v10.9 / iOS 7 and later 535 * 536 * @param channels - channels to configure 537 * @param action - enable/disable/size, etc 538 * @param result - action-specific returned value 539 * @param destination - action-specific default destination 540 */ 541 virtual IOReturn configureReport(IOReportChannelList *channels, 542 IOReportConfigureAction action, 543 void *result, 544 void *destination); 545 546 /*! @function updateReport 547 * @abstract request current data for the specified channels 548 * @availability SPI on OS X 10.9 / iOS 7 and later 549 * 550 * @param channels - channels to be updated 551 * @param action - type/style of update 552 * @param result - returned details about what was updated 553 * @param destination - destination for this update (action-specific) 554 */ 555 virtual IOReturn updateReport(IOReportChannelList *channels, 556 IOReportUpdateAction action, 557 void *result, 558 void *destination); 559 560 protected: 561 562 /* these are helper methods for DriverKit */ 563 IOReturn _ConfigureReport(IOReportChannelList *channels, 564 IOReportConfigureAction action, 565 void *result, 566 void *destination); 567 IOReturn _UpdateReport(IOReportChannelList *channels, 568 IOReportUpdateAction action, 569 void *result, 570 void *destination); 571 572 private: 573 #if __LP64__ 574 OSMetaClassDeclareReservedUsedX86(IOService, 0); 575 OSMetaClassDeclareReservedUsedX86(IOService, 1); 576 OSMetaClassDeclareReservedUnused(IOService, 2); 577 OSMetaClassDeclareReservedUnused(IOService, 3); 578 OSMetaClassDeclareReservedUnused(IOService, 4); 579 OSMetaClassDeclareReservedUnused(IOService, 5); 580 OSMetaClassDeclareReservedUnused(IOService, 6); 581 OSMetaClassDeclareReservedUnused(IOService, 7); 582 #else 583 OSMetaClassDeclareReservedUsedX86(IOService, 0); 584 OSMetaClassDeclareReservedUsedX86(IOService, 1); 585 OSMetaClassDeclareReservedUsedX86(IOService, 2); 586 OSMetaClassDeclareReservedUsedX86(IOService, 3); 587 OSMetaClassDeclareReservedUsedX86(IOService, 4); 588 OSMetaClassDeclareReservedUsedX86(IOService, 5); 589 OSMetaClassDeclareReservedUsedX86(IOService, 6); 590 OSMetaClassDeclareReservedUsedX86(IOService, 7); 591 #endif 592 593 OSMetaClassDeclareReservedUnused(IOService, 8); 594 OSMetaClassDeclareReservedUnused(IOService, 9); 595 OSMetaClassDeclareReservedUnused(IOService, 10); 596 OSMetaClassDeclareReservedUnused(IOService, 11); 597 OSMetaClassDeclareReservedUnused(IOService, 12); 598 OSMetaClassDeclareReservedUnused(IOService, 13); 599 OSMetaClassDeclareReservedUnused(IOService, 14); 600 OSMetaClassDeclareReservedUnused(IOService, 15); 601 OSMetaClassDeclareReservedUnused(IOService, 16); 602 OSMetaClassDeclareReservedUnused(IOService, 17); 603 OSMetaClassDeclareReservedUnused(IOService, 18); 604 OSMetaClassDeclareReservedUnused(IOService, 19); 605 OSMetaClassDeclareReservedUnused(IOService, 20); 606 OSMetaClassDeclareReservedUnused(IOService, 21); 607 OSMetaClassDeclareReservedUnused(IOService, 22); 608 OSMetaClassDeclareReservedUnused(IOService, 23); 609 OSMetaClassDeclareReservedUnused(IOService, 24); 610 OSMetaClassDeclareReservedUnused(IOService, 25); 611 OSMetaClassDeclareReservedUnused(IOService, 26); 612 OSMetaClassDeclareReservedUnused(IOService, 27); 613 OSMetaClassDeclareReservedUnused(IOService, 28); 614 OSMetaClassDeclareReservedUnused(IOService, 29); 615 OSMetaClassDeclareReservedUnused(IOService, 30); 616 OSMetaClassDeclareReservedUnused(IOService, 31); 617 OSMetaClassDeclareReservedUnused(IOService, 32); 618 OSMetaClassDeclareReservedUnused(IOService, 33); 619 OSMetaClassDeclareReservedUnused(IOService, 34); 620 OSMetaClassDeclareReservedUnused(IOService, 35); 621 OSMetaClassDeclareReservedUnused(IOService, 36); 622 OSMetaClassDeclareReservedUnused(IOService, 37); 623 OSMetaClassDeclareReservedUnused(IOService, 38); 624 OSMetaClassDeclareReservedUnused(IOService, 39); 625 OSMetaClassDeclareReservedUnused(IOService, 40); 626 OSMetaClassDeclareReservedUnused(IOService, 41); 627 OSMetaClassDeclareReservedUnused(IOService, 42); 628 OSMetaClassDeclareReservedUnused(IOService, 43); 629 OSMetaClassDeclareReservedUnused(IOService, 44); 630 OSMetaClassDeclareReservedUnused(IOService, 45); 631 OSMetaClassDeclareReservedUnused(IOService, 46); 632 OSMetaClassDeclareReservedUnused(IOService, 47); 633 634 public: 635 /*! @function getState 636 * @abstract Accessor for IOService state bits, not normally needed or used outside IOService. 637 * @result State bits for the IOService, eg. <code>kIOServiceInactiveState</code>, <code>kIOServiceRegisteredState</code>. */ 638 639 virtual IOOptionBits getState( void ) const; 640 641 /*! @function isInactive 642 * @abstract Checks if the IOService object has been terminated, and is in the process of being destroyed. 643 * @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. 644 * @result <code>true</code> if the IOService object has been terminated. */ 645 646 bool isInactive( void ) const; 647 648 /* Stack creation */ 649 650 /*! @function registerService 651 * @abstract Starts the registration process for a newly discovered IOService object. 652 * @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. 653 * @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. */ 654 655 virtual void registerService( IOOptionBits options = 0 ); 656 657 /*! @function probe 658 * @abstract During an IOService object's instantiation, probes a matched service to see if it can be used. 659 * @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. 660 * @param provider The registered IOService object that matches a driver personality's matching dictionary. 661 * @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. 662 * @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>. */ 663 664 virtual LIBKERN_RETURNS_NOT_RETAINED IOService * probe( IOService * provider, 665 SInt32 * score ); 666 667 /*! @function start 668 * @abstract During an IOService object's instantiation, starts the IOService object that has been selected to run on the provider. 669 * @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. 670 * @result <code>true</code> if the start was successful; <code>false</code> otherwise (which will cause the instance to be detached and usually freed). */ 671 672 virtual bool start( IOService * provider ); 673 674 /*! @function stop 675 * @abstract During an IOService termination, the stop method is called in its clients before they are detached & it is destroyed. 676 * @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. */ 677 678 virtual void stop( IOService * provider ); 679 680 /* Open / Close */ 681 682 /*! @function open 683 * @abstract Requests active access to a provider. 684 * @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. 685 * @param forClient Designates the client of the provider requesting the open. 686 * @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. 687 * @param arg Family specific arguments which are ignored by IOService. 688 * @result <code>true</code> if the open was successful; <code>false</code> otherwise. */ 689 690 virtual bool open( IOService * forClient, 691 IOOptionBits options = 0, 692 void * arg = NULL ); 693 694 /*! @function close 695 * @abstract Releases active access to a provider. 696 * @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. 697 * @param forClient Designates the client of the provider requesting the close. 698 * @param options Options available for the close. The provider family may implement options for close; IOService defines none. */ 699 700 virtual void close( IOService * forClient, 701 IOOptionBits options = 0 ); 702 703 /*! @function isOpen 704 * @abstract Determines whether a specific, or any, client has an IOService object open. 705 * @discussion Returns the open state of an IOService object with respect to the specified client, or when it is open by any client. 706 * @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. 707 * @result <code>true</code> if the specific, or any, client has the IOService object open. */ 708 709 virtual bool isOpen( const IOService * forClient = NULL ) const; 710 711 /*! @function handleOpen 712 * @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses). 713 * @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. 714 * @param forClient Designates the client of the provider requesting the open. 715 * @param options Options for the open, may be interpreted by the implementor of <code>handleOpen</code>. 716 * @result <code>true</code>if the open was successful; <code>false</code> otherwise. */ 717 718 virtual bool handleOpen( IOService * forClient, 719 IOOptionBits options, 720 void * arg ); 721 722 /*! @function handleClose 723 * @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses). 724 * @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. 725 * @param forClient Designates the client of the provider requesting the close. 726 * @param options Options for the close, may be interpreted by the implementor of @link handleOpen handleOpen@/link. */ 727 728 virtual void handleClose( IOService * forClient, 729 IOOptionBits options ); 730 731 /*! @function handleIsOpen 732 * @abstract Controls the open / close behavior of an IOService object (overrideable by subclasses). 733 * @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. 734 * @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. 735 * @result <code>true</code> if the specific, or any, client has the IOService object open. */ 736 737 virtual bool handleIsOpen( const IOService * forClient ) const; 738 739 /* Stacking change */ 740 741 /*! @function terminate 742 * @abstract Makes an IOService object inactive and begins its destruction. 743 * @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. 744 * @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. */ 745 746 virtual bool terminate( IOOptionBits options = 0 ); 747 748 /*! @function finalize 749 * @abstract Finalizes the destruction of an IOService object. 750 * @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. 751 * @param options The options passed to the @link terminate terminate@/link method of the IOService object are passed on to <code>finalize</code>. 752 * @result <code>true</code>. */ 753 754 virtual bool finalize( IOOptionBits options ); 755 756 /*! @function init 757 * @abstract Initializes generic IOService data structures (expansion data, etc). */ 758 virtual bool init( OSDictionary * dictionary = NULL ) APPLE_KEXT_OVERRIDE; 759 760 /*! @function init 761 * @abstract Initializes generic IOService data structures (expansion data, etc). */ 762 virtual bool init( IORegistryEntry * from, 763 const IORegistryPlane * inPlane ) APPLE_KEXT_OVERRIDE; 764 765 /*! @function free 766 * @abstract Frees data structures that were allocated when power management was initialized on this service. */ 767 768 virtual void free( void ) APPLE_KEXT_OVERRIDE; 769 770 /*! @function lockForArbitration 771 * @abstract Locks an IOService object against changes in state or ownership. 772 * @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. 773 * @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>. */ 774 775 virtual bool lockForArbitration( bool isSuccessRequired = true ); 776 777 /*! @function unlockForArbitration 778 * @abstract Unlocks an IOService obkect after a successful @link lockForArbitration lockForArbitration@/link. 779 * @discussion A thread granted exclusive access to an IOService object should release it with <code>unlockForArbitration</code>. */ 780 781 virtual void unlockForArbitration( void ); 782 783 #ifdef XNU_KERNEL_PRIVATE 784 static uint32_t isLockedForArbitration(IOService * service); 785 void setMachPortHoldDestroy(bool holdDestroy); 786 bool machPortHoldDestroy(); 787 #endif /* XNU_KERNEL_PRIVATE */ 788 789 790 /*! @function terminateClient 791 * @abstract Passes a termination up the stack. 792 * @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. 793 * @param client The client of the terminated provider. 794 * @param options Options originally passed to @link terminate terminate@/link, plus <code>kIOServiceRecursing</code>. 795 * @result result of the terminate request on the client. */ 796 797 virtual bool terminateClient( IOService * client, IOOptionBits options ); 798 799 /* Busy state indicates discovery, matching or termination is in progress */ 800 801 /*! @function getBusyState 802 * @abstract Returns the <code>busyState</code> of an IOService object. 803 * @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. 804 * @result The <code>busyState</code> value. */ 805 806 virtual UInt32 getBusyState( void ); 807 808 /*! @function adjustBusy 809 * @abstract Adjusts the <code>busyState</code> of an IOService object. 810 * @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). 811 * @param delta The delta to be applied to the IOService object's <code>busyState</code>. */ 812 813 virtual void adjustBusy( SInt32 delta ); 814 815 #ifdef XNU_KERNEL_PRIVATE 816 /*! @function waitQuietWithOptions 817 * @abstract Waits for an IOService object's <code>busyState</code> to be zero. 818 * @discussion Blocks the caller until an IOService object is non busy. 819 * @param timeout The maximum time to wait in nanoseconds. Default is to wait forever. 820 * @param options Options to configure behavior of this call 821 * @result Returns an error code if Mach synchronization primitives fail, <code>kIOReturnTimeout</code>, or <code>kIOReturnSuccess</code>. */ 822 823 IOReturn waitQuietWithOptions(uint64_t timeout = UINT64_MAX, IOOptionBits options = 0); 824 #endif /* XNU_KERNEL_PRIVATE */ 825 826 APPLE_KEXT_COMPATIBILITY_VIRTUAL 827 IOReturn waitQuiet(mach_timespec_t * timeout) 828 APPLE_KEXT_DEPRECATED; 829 830 /*! @function waitQuiet 831 * @abstract Waits for an IOService object's <code>busyState</code> to be zero. 832 * @discussion Blocks the caller until an IOService object is non busy. 833 * @param timeout The maximum time to wait in nanoseconds. Default is to wait forever. 834 * @result Returns an error code if Mach synchronization primitives fail, <code>kIOReturnTimeout</code>, or <code>kIOReturnSuccess</code>. */ 835 836 IOReturn waitQuiet(uint64_t timeout = UINT64_MAX); 837 838 /* Matching */ 839 840 /*! @function matchPropertyTable 841 * @abstract Allows a registered IOService object to implement family specific matching. 842 * @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. 843 * @param table The dictionary of properties to be matched against. 844 * @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. 845 * @result <code>false</code> if the family considers the matching dictionary does not match in properties it understands; <code>true</code> otherwise. */ 846 847 virtual bool matchPropertyTable( OSDictionary * table, 848 SInt32 * score ); 849 850 virtual bool matchPropertyTable( OSDictionary * table ); 851 852 /*! @function matchLocation 853 * @abstract Allows a registered IOService object to direct location matching. 854 * @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. 855 * @param client The IOService object at which matching is taking place. 856 * @result Returns the IOService instance to be used for location matching. */ 857 858 virtual LIBKERN_RETURNS_NOT_RETAINED IOService * matchLocation( IOService * client ); 859 860 /* Resource service */ 861 862 /*! @function publishResource 863 * @abstract Uses the resource service to publish a property. 864 * @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. 865 * @param key An OSSymbol key that globally identifies the object. 866 * @param value The object to be published. */ 867 868 static void publishResource( const OSSymbol * key, OSObject * value = NULL ); 869 static void publishUserResource( const OSSymbol * key, OSObject * value = NULL ); 870 871 /*! @function publishResource 872 * @abstract Uses the resource service to publish a property. 873 * @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. 874 * @param key A C string key that globally identifies the object. 875 * @param value The object to be published. */ 876 877 static void publishResource( const char * key, OSObject * value = NULL ); 878 virtual bool addNeededResource( const char * key ); 879 880 /* Notifications */ 881 882 /*! @function addNotification 883 * @abstract Deprecated use addMatchingNotification(). Adds a persistant notification handler to be notified of IOService events. 884 * @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. 885 * @param type An OSSymbol identifying the type of notification and IOService state: 886 * <br> <code>gIOPublishNotification</code> Delivered when an IOService object is registered. 887 * <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. 888 * <br> <code>gIOMatchedNotification</code> Delivered when an IOService object has been matched with all client drivers, and they have been probed and started. 889 * <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. 890 * <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. 891 * <br> <code>gIOTerminatedNotification</code> Delivered immediately when an IOService object has been terminated, making it inactive. 892 * @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. 893 * @param handler A C function callback to deliver notifications. 894 * @param target An instance reference for the callback's use. 895 * @param ref A reference constant for the callback's use. 896 * @param priority A constant ordering all notifications of a each type. 897 * @result An instance of an IONotifier object that can be used to control or destroy the notification request. */ 898 899 static OSPtr<IONotifier> addNotification( 900 const OSSymbol * type, OSDictionary * matching, 901 IOServiceNotificationHandler handler, 902 void * target, void * ref = NULL, 903 SInt32 priority = 0 ) 904 APPLE_KEXT_DEPRECATED; 905 906 /*! @function addMatchingNotification 907 * @abstract Adds a persistant notification handler to be notified of IOService events. 908 * @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. 909 * @param type An OSSymbol identifying the type of notification and IOService state: 910 * <br> <code>gIOPublishNotification</code> Delivered when an IOService object is registered. 911 * <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. 912 * <br> <code>gIOMatchedNotification</code> Delivered when an IOService object has been matched with all client drivers, and they have been probed and started. 913 * <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. 914 * <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. 915 * <br> <code>gIOTerminatedNotification</code> Delivered immediately when an IOService object has been terminated, making it inactive. 916 * @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). 917 * @param handler A C function callback to deliver notifications. 918 * @param target An instance reference for the callback's use. 919 * @param ref A reference constant for the callback's use. 920 * @param priority A constant ordering all notifications of a each type. 921 * @result An instance of an IONotifier object that can be used to control or destroy the notification request. */ 922 923 static IONotifier * addMatchingNotification( 924 const OSSymbol * type, OSDictionary * matching, 925 IOServiceMatchingNotificationHandler handler, 926 void * target, void * ref = NULL, 927 SInt32 priority = 0 ); 928 929 930 #ifdef __BLOCKS__ 931 static IONotifier * addMatchingNotification( 932 const OSSymbol * type, OSDictionary * matching, 933 SInt32 priority, 934 IOServiceMatchingNotificationHandlerBlock handler); 935 #endif /* __BLOCKS__ */ 936 937 /*! @function waitForService 938 * @abstract Deprecated use waitForMatchingService(). Waits for a matching to service to be published. 939 * @discussion Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched. 940 * @param matching The matching dictionary describing the desired IOService object. <code>waitForService</code> consumes one reference of the matching dictionary. 941 * @param timeout The maximum time to wait. 942 * @result A published IOService object matching the supplied dictionary. */ 943 944 static LIBKERN_RETURNS_NOT_RETAINED IOService * waitForService( 945 LIBKERN_CONSUMED OSDictionary * matching, 946 mach_timespec_t * timeout = NULL); 947 948 /*! @function waitForMatchingService 949 * @abstract Waits for a matching to service to be published. 950 * @discussion Provides a method of waiting for an IOService object matching the supplied matching dictionary to be registered and fully matched. 951 * @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.) 952 * @param timeout The maximum time to wait in nanoseconds. Default is to wait forever. 953 * @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.) */ 954 955 static OSPtr<IOService> waitForMatchingService( OSDictionary * matching, 956 uint64_t timeout = UINT64_MAX); 957 958 #ifdef XNU_KERNEL_PRIVATE 959 static IOService * waitForMatchingServiceWithToken( OSDictionary * matching, 960 uint64_t timeout, IOUserServerCheckInToken * token ); 961 #endif 962 963 /*! @function getMatchingServices 964 * @abstract Finds the set of current published IOService objects matching a matching dictionary. 965 * @discussion Provides a method of finding the current set of published IOService objects matching the supplied matching dictionary. 966 * @param matching The matching dictionary describing the desired IOService objects. 967 * @result An instance of an iterator over a set of IOService objects. To be released by the caller. */ 968 969 static OSPtr<OSIterator> getMatchingServices( OSDictionary * matching ); 970 971 /*! @function copyMatchingService 972 * @abstract Finds one of the current published IOService objects matching a matching dictionary. 973 * @discussion Provides a method to find one member of the set of published IOService objects matching the supplied matching dictionary. 974 * @param matching The matching dictionary describing the desired IOService object. 975 * @result The IOService object or NULL. To be released by the caller. */ 976 977 static OSPtr<IOService> copyMatchingService( OSDictionary * matching ); 978 979 public: 980 /* Helpers to make matching dictionaries for simple cases, 981 * they add keys to an existing dictionary, or create one. */ 982 983 /*! @function serviceMatching 984 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match. 985 * @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. 986 * @param className The class name, as a const C string. Class matching is successful on IOService objects of this class or any subclass. 987 * @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. 988 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 989 990 static OSPtr<OSDictionary> serviceMatching( const char * className, 991 OSDictionary * table = NULL ); 992 993 #if __cplusplus >= 201703L 994 /*! @function serviceMatching 995 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match. 996 * @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. 997 * @param className The class name, as a const C string. Class matching is successful on IOService objects of this class or any subclass. 998 * @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. 999 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1000 1001 static OSSharedPtr<OSDictionary> serviceMatching( const char * className, 1002 OSSharedPtr<OSDictionary> table); 1003 #endif 1004 1005 /*! @function serviceMatching 1006 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match. 1007 * @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. 1008 * @param className The class name, as an OSString (which includes OSSymbol). Class matching is successful on IOService objects of this class or any subclass. 1009 * @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. 1010 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1011 1012 static OSPtr<OSDictionary> serviceMatching( const OSString * className, 1013 OSDictionary * table = NULL ); 1014 1015 #if __cplusplus >= 201703L 1016 /*! @function serviceMatching 1017 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService class match. 1018 * @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. 1019 * @param className The class name, as an OSString (which includes OSSymbol). Class matching is successful on IOService objects of this class or any subclass. 1020 * @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. 1021 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1022 1023 static OSSharedPtr<OSDictionary> serviceMatching( const OSString * className, 1024 OSSharedPtr<OSDictionary> table); 1025 #endif 1026 1027 /*! @function nameMatching 1028 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match. 1029 * @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. 1030 * @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. 1031 * @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. 1032 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1033 1034 static OSPtr<OSDictionary> nameMatching( const char * name, 1035 OSDictionary * table = NULL ); 1036 1037 #if __cplusplus >= 201703L 1038 /*! @function nameMatching 1039 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match. 1040 * @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. 1041 * @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. 1042 * @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. 1043 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1044 1045 static OSSharedPtr<OSDictionary> nameMatching( const char * name, 1046 OSSharedPtr<OSDictionary> table); 1047 #endif 1048 1049 /*! @function nameMatching 1050 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match. 1051 * @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. 1052 * @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. 1053 * @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. 1054 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1055 1056 static OSPtr<OSDictionary> nameMatching( const OSString* name, 1057 OSDictionary * table = NULL ); 1058 1059 #if __cplusplus >= 201703L 1060 /*! @function nameMatching 1061 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService name match. 1062 * @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. 1063 * @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. 1064 * @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. 1065 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1066 1067 static OSSharedPtr<OSDictionary> nameMatching( const OSString* name, 1068 OSSharedPtr<OSDictionary> table); 1069 #endif 1070 1071 /*! @function resourceMatching 1072 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match. 1073 * @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. 1074 * @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. 1075 * @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. 1076 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1077 1078 static OSPtr<OSDictionary> resourceMatching( const char * name, 1079 OSDictionary * table = NULL ); 1080 1081 #if __cplusplus >= 201703L 1082 /*! @function resourceMatching 1083 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match. 1084 * @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. 1085 * @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. 1086 * @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. 1087 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1088 1089 static OSSharedPtr<OSDictionary> resourceMatching( const char * name, 1090 OSSharedPtr<OSDictionary> table); 1091 #endif 1092 1093 /*! @function resourceMatching 1094 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match. 1095 * @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. 1096 * @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. 1097 * @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. 1098 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1099 1100 static OSPtr<OSDictionary> resourceMatching( const OSString * name, 1101 OSDictionary * table = NULL ); 1102 1103 #if __cplusplus >= 201703L 1104 /*! @function resourceMatching 1105 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a resource service match. 1106 * @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. 1107 * @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. 1108 * @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. 1109 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1110 1111 static OSSharedPtr<OSDictionary> resourceMatching( const OSString * name, 1112 OSSharedPtr<OSDictionary> table); 1113 #endif 1114 1115 1116 /*! @function propertyMatching 1117 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService phandle match. 1118 * @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. 1119 * @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. 1120 * @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. 1121 * @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. 1122 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1123 1124 static OSPtr<OSDictionary> propertyMatching( const OSSymbol * key, const OSObject * value, 1125 OSDictionary * table = NULL ); 1126 1127 #if __cplusplus >= 201703L 1128 /*! @function propertyMatching 1129 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify an IOService phandle match. 1130 * @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. 1131 * @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. 1132 * @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. 1133 * @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. 1134 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1135 1136 static OSSharedPtr<OSDictionary> propertyMatching( const OSSymbol * key, const OSObject * value, 1137 OSSharedPtr<OSDictionary> table); 1138 #endif 1139 1140 /*! @function registryEntryIDMatching 1141 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a IORegistryEntryID match. 1142 * @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. 1143 * @param entryID The service's ID. Matching is successful on the IOService object that return that ID from the <code>IORegistryEntry::getRegistryEntryID()</code> method. 1144 * @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. 1145 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1146 1147 static OSDictionary * registryEntryIDMatching( uint64_t entryID, 1148 OSDictionary * table = NULL ); 1149 1150 #if __cplusplus >= 201703L 1151 /*! @function registryEntryIDMatching 1152 * @abstract Creates a matching dictionary, or adds matching properties to an existing dictionary, that specify a IORegistryEntryID match. 1153 * @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. 1154 * @param entryID The service's ID. Matching is successful on the IOService object that return that ID from the <code>IORegistryEntry::getRegistryEntryID()</code> method. 1155 * @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. 1156 * @result The matching dictionary created, or passed in, is returned on success, or zero on failure. */ 1157 1158 static OSSharedPtr<OSDictionary> registryEntryIDMatching( uint64_t entryID, 1159 OSSharedPtr<OSDictionary> table); 1160 #endif 1161 1162 1163 /*! @function addLocation 1164 * @abstract Adds a location matching property to an existing dictionary. 1165 * @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. 1166 * @param table The matching properties are added to the specified dictionary, which must be non-zero. 1167 * @result The location matching dictionary created is returned on success, or zero on failure. */ 1168 1169 static OSPtr<OSDictionary> addLocation( OSDictionary * table ); 1170 1171 /* Helpers for matching dictionaries. */ 1172 1173 /*! @function compareProperty 1174 * @abstract Compares a property in a matching dictionary with an IOService object's property table. 1175 * @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. 1176 * @param matching The matching dictionary, which must be non-zero. 1177 * @param key The dictionary key specifying the property to be compared, as a C string. 1178 * @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. */ 1179 1180 virtual bool compareProperty( OSDictionary * matching, 1181 const char * key ); 1182 /*! @function compareProperty 1183 * @abstract Compares a property in a matching dictionary with an IOService object's property table. 1184 * @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. 1185 * @param matching The matching dictionary, which must be non-zero. 1186 * @param key The dictionary key specifying the property to be compared, as an OSString (which includes OSSymbol). 1187 * @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. */ 1188 1189 virtual bool compareProperty( OSDictionary * matching, 1190 const OSString * key ); 1191 1192 /*! @function compareProperties 1193 * @abstract Compares a set of properties in a matching dictionary with an IOService object's property table. 1194 * @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. 1195 * @param matching The matching dictionary, which must be non-zero. 1196 * @param keys A collection (eg. OSSet, OSArray, OSDictionary) which should contain OSStrings (or OSSymbols) that specify the property keys to be compared. 1197 * @result Success if <code>compareProperty</code> returns <code>true</code> for each key in the collection; otherwise failure. */ 1198 1199 virtual bool compareProperties( OSDictionary * matching, 1200 OSCollection * keys ); 1201 1202 /* Client / provider accessors */ 1203 1204 /*! @function attach 1205 * @abstract Attaches an IOService client to a provider in the I/O Registry. 1206 * @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. 1207 * @param provider The IOService object which will serve as this object's provider. 1208 * @result <code>false</code> if the provider is inactive or on a resource failure; otherwise <code>true</code>. */ 1209 1210 virtual bool attach( IOService * provider ); 1211 1212 /*! @function detach 1213 * @abstract Detaches an IOService client from a provider in the I/O Registry. 1214 * @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. 1215 * @param provider The IOService object to detach from. */ 1216 1217 virtual void detach( IOService * provider ); 1218 1219 /*! @function getProvider 1220 * @abstract Returns an IOService object's primary provider. 1221 * @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. 1222 * @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. */ 1223 1224 virtual IOService * getProvider( void ) const; 1225 1226 /*! @function getWorkLoop 1227 * @abstract Returns the current work loop or <code>provider->getWorkLoop</code>. 1228 * @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. 1229 * @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.*/ 1230 1231 virtual IOWorkLoop * getWorkLoop() const; 1232 1233 /*! @function getProviderIterator 1234 * @abstract Returns an iterator over an IOService object's providers. 1235 * @discussion For those few IOService objects that obtain service from multiple providers, this method supplies an iterator over a client's providers. 1236 * @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. */ 1237 1238 virtual OSPtr<OSIterator> getProviderIterator( void ) const; 1239 1240 /*! @function getOpenProviderIterator 1241 * @abstract Returns an iterator over an client's providers that are currently opened by the client. 1242 * @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. 1243 * @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. */ 1244 1245 virtual OSPtr<OSIterator> getOpenProviderIterator( void ) const; 1246 1247 /*! @function getClient 1248 * @abstract Returns an IOService object's primary client. 1249 * @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. 1250 * @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. */ 1251 1252 virtual IOService * getClient( void ) const; 1253 1254 /*! @function getClientIterator 1255 * @abstract Returns an iterator over an IOService object's clients. 1256 * @discussion For IOService objects that may have multiple clients, this method supplies an iterator over a provider's clients. 1257 * @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. */ 1258 1259 virtual OSPtr<OSIterator> getClientIterator( void ) const; 1260 1261 /*! @function getOpenClientIterator 1262 * @abstract Returns an iterator over a provider's clients that currently have opened the provider. 1263 * @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. 1264 * @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. */ 1265 1266 virtual OSPtr<OSIterator> getOpenClientIterator( void ) const; 1267 1268 /*! @function callPlatformFunction 1269 * @abstract Calls the platform function with the given name. 1270 * @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. 1271 * @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. 1272 * @param waitForFunction If <code>true</code>, <code>callPlatformFunction</code> will not return until the function has been called. 1273 * @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.*/ 1274 1275 virtual IOReturn callPlatformFunction( const OSSymbol * functionName, 1276 bool waitForFunction, 1277 void *param1, void *param2, 1278 void *param3, void *param4 ); 1279 1280 virtual IOReturn callPlatformFunction( const char * functionName, 1281 bool waitForFunction, 1282 void *param1, void *param2, 1283 void *param3, void *param4 ); 1284 1285 1286 /* Some accessors */ 1287 1288 /*! @function getPlatform 1289 * @abstract Returns a pointer to the platform expert instance for the computer. 1290 * @discussion This method provides an accessor to the platform expert instance for the computer. 1291 * @result A pointer to the IOPlatformExpert instance. It should not be released by the caller. */ 1292 1293 static IOPlatformExpert * getPlatform( void ); 1294 1295 /*! @function getPMRootDomain 1296 * @abstract Returns a pointer to the power management root domain instance for the computer. 1297 * @discussion This method provides an accessor to the power management root domain instance for the computer. 1298 * @result A pointer to the power management root domain instance. It should not be released by the caller. */ 1299 1300 static class IOPMrootDomain * getPMRootDomain( void ); 1301 1302 /*! @function getServiceRoot 1303 * @abstract Returns a pointer to the root of the service plane. 1304 * @discussion This method provides an accessor to the root of the service plane for the computer. 1305 * @result A pointer to the IOService instance at the root of the service plane. It should not be released by the caller. */ 1306 1307 static IOService * getServiceRoot( void ); 1308 1309 /*! @function getResourceService 1310 * @abstract Returns a pointer to the IOResources service. 1311 * @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. 1312 * @result A pointer to the IOResources instance. It should not be released by the caller. */ 1313 1314 static IOService * getResourceService( void ); 1315 1316 static IOService * getSystemStateNotificationService(void); 1317 1318 /* Allocate resources for a matched service */ 1319 1320 /*! @function getResources 1321 * @abstract Allocates any needed resources for a published IOService object before clients attach. 1322 * @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. 1323 * @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. */ 1324 1325 virtual IOReturn getResources( void ); 1326 1327 /* Device memory accessors */ 1328 1329 /*! @function getDeviceMemoryCount 1330 * @abstract Returns a count of the physical memory ranges available for a device. 1331 * @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. 1332 * @result An integer count of the number of ranges available. */ 1333 1334 virtual IOItemCount getDeviceMemoryCount( void ); 1335 1336 /*! @function getDeviceMemoryWithIndex 1337 * @abstract Returns an instance of IODeviceMemory representing one of a device's memory mapped ranges. 1338 * @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. 1339 * @param index An index into the array of ranges assigned to the device. 1340 * @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. */ 1341 1342 virtual IODeviceMemory * getDeviceMemoryWithIndex( unsigned int index ); 1343 1344 /*! @function mapDeviceMemoryWithIndex 1345 * @abstract Maps a physical range of a device. 1346 * @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. 1347 * @param index An index into the array of ranges assigned to the device. 1348 * @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. */ 1349 1350 virtual IOMemoryMap * mapDeviceMemoryWithIndex( unsigned int index, 1351 IOOptionBits options = 0 ); 1352 1353 /*! @function getDeviceMemory 1354 * @abstract Returns the array of IODeviceMemory objects representing a device's memory mapped ranges. 1355 * @discussion This method returns an array of IODeviceMemory objects representing the physical memory ranges allocated to a memory mapped device. 1356 * @result An OSArray of IODeviceMemory objects, or zero if none are available. The array is retained by the provider, so is valid while attached. */ 1357 1358 virtual OSArray * getDeviceMemory( void ); 1359 1360 /*! @function setDeviceMemory 1361 * @abstract Sets the array of IODeviceMemory objects representing a device's memory mapped ranges. 1362 * @discussion This method sets an array of IODeviceMemory objects representing the physical memory ranges allocated to a memory mapped device. 1363 * @param array An OSArray of IODeviceMemory objects, or zero if none are available. The array will be retained by the object. */ 1364 1365 virtual void setDeviceMemory( OSArray * array ); 1366 1367 /* Interrupt accessors */ 1368 1369 /*! @function registerInterrupt 1370 * @abstract Registers a C function interrupt handler for a device supplying interrupts. 1371 * @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. 1372 * @param source The index of the interrupt source in the device. 1373 * @param target An object instance to be passed to the interrupt handler. 1374 * @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. 1375 * @param refCon A reference constant for the handler's use. 1376 * @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. */ 1377 1378 virtual IOReturn registerInterrupt(int source, OSObject *target, 1379 IOInterruptAction handler, 1380 void *refCon = NULL); 1381 1382 #ifdef __BLOCKS__ 1383 /*! @function registerInterrupt 1384 * @abstract Registers a block handler for a device supplying interrupts. 1385 * @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. 1386 * @param source The index of the interrupt source in the device. 1387 * @param target An object instance to be passed to the interrupt handler. 1388 * @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. 1389 * @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. */ 1390 1391 IOReturn registerInterruptBlock(int source, OSObject *target, 1392 IOInterruptActionBlock handler); 1393 #endif /* __BLOCKS__ */ 1394 1395 /*! @function unregisterInterrupt 1396 * @abstract Removes a C function interrupt handler for a device supplying hardware interrupts. 1397 * @discussion This method removes a C function interrupt handler previously installed with @link registerInterrupt registerInterrupt@/link. 1398 * @param source The index of the interrupt source in the device. 1399 * @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */ 1400 1401 virtual IOReturn unregisterInterrupt(int source); 1402 1403 /*! @function addInterruptStatistics 1404 * @abstract Adds a statistics object to the IOService for the given interrupt. 1405 * @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. 1406 * @param statistics The IOInterruptAccountingData container we wish to associate the IOService with. 1407 * @param source The index of the interrupt source in the device. */ 1408 IOReturn addInterruptStatistics(IOInterruptAccountingData * statistics, int source); 1409 1410 /*! @function removeInterruptStatistics 1411 * @abstract Removes any statistics from the IOService for the given interrupt. 1412 * @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. 1413 * @param source The index of the interrupt source in the device. */ 1414 IOReturn removeInterruptStatistics(int source); 1415 1416 /*! @function getInterruptType 1417 * @abstract Returns the type of interrupt used for a device supplying hardware interrupts. 1418 * @param source The index of the interrupt source in the device. 1419 * @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. 1420 * @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */ 1421 1422 virtual IOReturn getInterruptType(int source, int *interruptType); 1423 1424 /*! @function enableInterrupt 1425 * @abstract Enables a device interrupt. 1426 * @discussion It is the caller's responsiblity to keep track of the enable state of the interrupt source. 1427 * @param source The index of the interrupt source in the device. 1428 * @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */ 1429 1430 virtual IOReturn enableInterrupt(int source); 1431 1432 /*! @function disableInterrupt 1433 * @abstract Synchronously disables a device interrupt. 1434 * @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. 1435 * @param source The index of the interrupt source in the device. 1436 * @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */ 1437 1438 virtual IOReturn disableInterrupt(int source); 1439 1440 /*! @function causeInterrupt 1441 * @abstract Causes a device interrupt to occur. 1442 * @discussion Emulates a hardware interrupt, to be called from task level. 1443 * @param source The index of the interrupt source in the device. 1444 * @result An IOReturn code (<code>kIOReturnNoInterrupt</code> is returned if the source is not valid). */ 1445 1446 virtual IOReturn causeInterrupt(int source); 1447 1448 /*! @function requestProbe 1449 * @abstract Requests that hardware be re-scanned for devices. 1450 * @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. 1451 * @param options Family defined options, not interpreted by IOService. 1452 * @result An IOReturn code. */ 1453 1454 virtual IOReturn requestProbe( IOOptionBits options ); 1455 1456 /* Generic API for non-data-path upstream calls */ 1457 1458 /*! @function message 1459 * @abstract Receives a generic message delivered from an attached provider. 1460 * @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. 1461 * @param type A type defined in <code>IOMessage.h</code> or defined by the provider family. 1462 * @param provider The provider from which the message originates. 1463 * @param argument An argument defined by the provider family, not used by IOService. 1464 * @result An IOReturn code defined by the message type. */ 1465 1466 virtual IOReturn message( UInt32 type, IOService * provider, 1467 void * argument = NULL ); 1468 1469 /*! @function messageClient 1470 * @abstract Sends a generic message to an attached client. 1471 * @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. 1472 * @param messageType A type defined in <code>IOMessage.h</code> or defined by the provider family. 1473 * @param client A client of the IOService to send the message. 1474 * @param messageArgument An argument defined by the provider family, not used by IOService. 1475 * @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. 1476 * @result The return code from the client message call. */ 1477 1478 virtual IOReturn messageClient( UInt32 messageType, OSObject * client, 1479 void * messageArgument = NULL, vm_size_t argSize = 0 ); 1480 1481 /*! @function messageClients 1482 * @abstract Sends a generic message to all attached clients. 1483 * @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. 1484 * @param type A type defined in <code>IOMessage.h</code> or defined by the provider family. 1485 * @param argument An argument defined by the provider family, not used by IOService. 1486 * @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. 1487 * @result Any non-<code>kIOReturnSuccess</code> return codes returned by the clients, or <code>kIOReturnSuccess</code> if all return <code>kIOReturnSuccess</code>. */ 1488 1489 virtual IOReturn messageClients( UInt32 type, 1490 void * argument = NULL, vm_size_t argSize = 0 ); 1491 1492 virtual OSPtr<IONotifier> registerInterest( const OSSymbol * typeOfInterest, 1493 IOServiceInterestHandler handler, 1494 void * target, void * ref = NULL ); 1495 1496 #ifdef __BLOCKS__ 1497 OSPtr<IONotifier> registerInterest(const OSSymbol * typeOfInterest, 1498 IOServiceInterestHandlerBlock handler); 1499 #endif /* __BLOCKS__ */ 1500 1501 virtual void applyToProviders( IOServiceApplierFunction applier, 1502 void * context ); 1503 1504 virtual void applyToClients( IOServiceApplierFunction applier, 1505 void * context ); 1506 1507 #ifdef __BLOCKS__ 1508 void applyToProviders(IOServiceApplierBlock applier); 1509 void applyToClients(IOServiceApplierBlock applier); 1510 #endif /* __BLOCKS__ */ 1511 1512 virtual void applyToInterested( const OSSymbol * typeOfInterest, 1513 OSObjectApplierFunction applier, 1514 void * context ); 1515 1516 virtual IOReturn acknowledgeNotification( IONotificationRef notification, 1517 IOOptionBits response ); 1518 1519 /* User client create */ 1520 1521 /*! @function newUserClient 1522 * @abstract Creates a connection for a non kernel client. 1523 * @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. 1524 * @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"}. 1525 * @param securityID A token representing the access level for the task. 1526 * @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. 1527 * @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. 1528 * @param properties A dictionary of additional properties for the connection. 1529 * @result A return code to be passed back to the caller of <code>IOServiceOpen</code>. */ 1530 1531 virtual IOReturn newUserClient( task_t owningTask, void * securityID, 1532 UInt32 type, OSDictionary * properties, 1533 LIBKERN_RETURNS_RETAINED IOUserClient ** handler ); 1534 1535 virtual IOReturn newUserClient( task_t owningTask, void * securityID, 1536 UInt32 type, 1537 LIBKERN_RETURNS_RETAINED IOUserClient ** handler ); 1538 1539 IOReturn newUserClient( task_t owningTask, void * securityID, 1540 UInt32 type, OSDictionary * properties, 1541 OSSharedPtr<IOUserClient>& handler ); 1542 1543 IOReturn newUserClient( task_t owningTask, void * securityID, 1544 UInt32 type, 1545 OSSharedPtr<IOUserClient>& handler ); 1546 1547 /* Return code utilities */ 1548 1549 /*! @function stringFromReturn 1550 * @abstract Supplies a programmer-friendly string from an IOReturn code. 1551 * @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. 1552 * @param rtn The IOReturn code. 1553 * @result A pointer to a constant string, or zero if the return code is unknown. */ 1554 1555 virtual const char * stringFromReturn( IOReturn rtn ); 1556 1557 /*! @function errnoFromReturn 1558 * @abstract Translates an IOReturn code to a BSD <code>errno</code>. 1559 * @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. 1560 * @param rtn The IOReturn code. 1561 * @result The BSD <code>errno</code> or <code>EIO</code> if unknown. */ 1562 1563 virtual int errnoFromReturn( IOReturn rtn ); 1564 1565 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1566 1567 #ifdef KERNEL_PRIVATE 1568 struct IOExclaveProxyState; 1569 1570 bool 1571 exclaveStart(IOService * provider, IOExclaveProxyState ** state); 1572 1573 // value for tb_endpoint_create_with_value(TB_TRANSPORT_TYPE_XNU, ...) 1574 uint64_t 1575 exclaveEndpoint(IOExclaveProxyState * pRef); 1576 1577 /*! @function exclaveAsyncNotificationRegister 1578 * @abstract Register an asynchronous notification to be signaled from the exclave driver 1579 * @discussion This function uses the default IOService workloop for locking the internal data structure to keep track of registered asynchronous notifications. 1580 * @param pRef Exclave proxy state 1581 * @param notification IOInterruptEventSource notification to register. This should be created with a `NULL` provider and index `0` and should be added to a workloop. 1582 * @param notificationID Out parameter for the notification ID. This is used by the exclave driver to signal the registered notification. It is the driver's responsibility to pass this ID to the exclave driver. 1583 * @result kIOReturnSuccess on success. See IOReturn.h for error codes. */ 1584 kern_return_t exclaveAsyncNotificationRegister(IOExclaveProxyState * pRef, IOInterruptEventSource *notification, uint32_t *notificationID); 1585 1586 #ifdef __BLOCKS__ 1587 /* ANE specific upcall registration */ 1588 1589 /*! @function exclaveRegisterUpcallSetPowerState 1590 * @abstract Register a handler for ANE exclave's setPowerState upcall 1591 * @param pRef Exclave proxy state 1592 * @param handler Upcall handler 1593 * @result kIOReturnSuccess on success. See IOReturn.h for error codes. */ 1594 kern_return_t exclaveRegisterANEUpcallSetPowerState(IOExclaveProxyState * pRef, ANEUpcallSetPowerStateHandler handler); 1595 1596 /*! @function exclaveRegisterUpcallWorkSubmit 1597 * @abstract Register a handler for ANE exclave's WorkSubmit upcall 1598 * @param pRef Exclave proxy state 1599 * @param handler Upcall handler 1600 * @result kIOReturnSuccess on success. See IOReturn.h for error codes. */ 1601 kern_return_t exclaveRegisterANEUpcallWorkSubmit(IOExclaveProxyState * pRef, ANEUpcallWorkHandler handler); 1602 kern_return_t exclaveRegisterANEUpcallWorkBegin(IOExclaveProxyState * pRef, ANEUpcallWorkHandler handler); 1603 kern_return_t exclaveRegisterANEUpcallWorkEnd(IOExclaveProxyState * pRef, ANEUpcallWorkHandler handler); 1604 #endif /* __BLOCKS__ */ 1605 1606 #ifdef XNU_KERNEL_PRIVATE 1607 // Interrupts 1608 bool 1609 exclaveRegisterInterrupt(IOExclaveProxyState * pRef, int index, bool noProvider); 1610 bool 1611 exclaveRemoveInterrupt(IOExclaveProxyState * pRef, int index); 1612 bool 1613 exclaveEnableInterrupt(IOExclaveProxyState * pRef, int index, bool enable); 1614 1615 // Timers 1616 bool 1617 exclaveRegisterTimer(IOExclaveProxyState * pRef, uint32_t *timer_id); 1618 bool 1619 exclaveRemoveTimer(IOExclaveProxyState * pRef, uint32_t timer_id); 1620 bool 1621 exclaveEnableTimer(IOExclaveProxyState * pRef, uint32_t timer_id, bool enable); 1622 bool 1623 exclaveTimerCancelTimeout(IOExclaveProxyState * pRef, uint32_t timer_id); 1624 bool 1625 exclaveTimerSetTimeout(IOExclaveProxyState * pRef, uint32_t timer_id, uint32_t options, AbsoluteTime interval, AbsoluteTime leeway, kern_return_t *kr); 1626 1627 /* Internal downcalls to EDK */ 1628 void 1629 exclaveInterruptOccurred(IOInterruptEventSource *eventSource, int count); 1630 void 1631 exclaveTimerFired(IOTimerEventSource *eventSource); 1632 1633 kern_return_t exclaveAsyncNotificationSignal(IOExclaveProxyState * pRef, uint32_t notificationID); 1634 #endif /* XNU_KERNEL_PRIVATE */ 1635 1636 #endif /* KERNEL_PRIVATE */ 1637 1638 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1639 /* * * * * * * * * * end of IOService API * * * * * * * */ 1640 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1641 1642 /* for IOInterruptController implementors */ 1643 1644 int _numInterruptSources; 1645 IOInterruptSource *_interruptSources; 1646 1647 /* overrides */ 1648 virtual bool serializeProperties( OSSerialize * s ) const APPLE_KEXT_OVERRIDE; 1649 1650 IOReturn requireMaxBusStall(UInt32 ns); 1651 IOReturn requireMaxInterruptDelay(uint32_t ns); 1652 1653 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1654 /* * * * * * * * * * * * Internals * * * * * * * * * * * */ 1655 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 1656 1657 #ifdef XNU_KERNEL_PRIVATE 1658 public: 1659 // called from other xnu components 1660 static void initialize( void ); 1661 static void setPlatform( IOPlatformExpert * platform); 1662 static void setPMRootDomain( class IOPMrootDomain * rootDomain ); 1663 static void publishPMRootDomain( void ); 1664 static IOReturn catalogNewDrivers( OSOrderedSet * newTables ); 1665 uint64_t getAccumulatedBusyTime( void ); 1666 static void updateConsoleUsers(OSArray * consoleUsers, IOMessage systemMessage, 1667 bool afterUserspaceReboot = false); 1668 static void consoleLockTimer(thread_call_param_t p0, thread_call_param_t p1); 1669 void setTerminateDefer(IOService * provider, bool defer); 1670 uint64_t getAuthorizationID( void ); 1671 IOReturn setAuthorizationID( uint64_t authorizationID ); 1672 void cpusRunning(void); 1673 void scheduleFinalize(bool now); 1674 static void willShutdown(); 1675 static void startDeferredMatches(); 1676 static void iokitDaemonLaunched(); 1677 void resetRematchProperties(); 1678 bool hasUserServer() const; 1679 static void userSpaceWillReboot(); 1680 static void userSpaceDidReboot(); 1681 kern_return_t CopyProperties_Local(OSDictionary ** properties); 1682 1683 IOStateNotificationItem * stateNotificationItemCopy(OSString * itemName, OSDictionary * schema); 1684 kern_return_t stateNotificationListenerAdd(OSArray * items, 1685 IOStateNotificationListenerRef * outRef, 1686 IOStateNotificationHandler handler); 1687 kern_return_t stateNotificationListenerRemove(IOStateNotificationListenerRef ref); 1688 1689 private: 1690 static IOReturn waitMatchIdle( UInt32 ms ); 1691 static OSPtr<IONotifier> installNotification( 1692 const OSSymbol * type, OSDictionary * matching, 1693 IOServiceMatchingNotificationHandler handler, 1694 void * target, void * ref, 1695 SInt32 priority, 1696 LIBKERN_RETURNS_RETAINED OSIterator ** existing); 1697 #if !defined(__LP64__) 1698 static OSPtr<IONotifier> installNotification( 1699 const OSSymbol * type, OSDictionary * matching, 1700 IOServiceNotificationHandler handler, 1701 void * target, void * ref, 1702 SInt32 priority, 1703 LIBKERN_RETURNS_RETAINED OSIterator ** existing); 1704 #endif /* !defined(__LP64__) */ 1705 #endif 1706 1707 private: 1708 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1709 bool checkResources( void ); 1710 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1711 bool checkResource( OSObject * matching ); 1712 1713 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1714 void probeCandidates( LIBKERN_CONSUMED OSOrderedSet * matches ); 1715 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1716 bool startCandidate( IOService * candidate ); 1717 1718 public: 1719 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1720 IOService * getClientWithCategory( const OSSymbol * category ) 1721 APPLE_KEXT_DEPRECATED; 1722 // copyClientWithCategory is the public replacement 1723 1724 #ifdef XNU_KERNEL_PRIVATE 1725 /* Callable within xnu source only - but require vtable entries to be visible */ 1726 public: 1727 #else 1728 private: 1729 #endif 1730 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1731 bool passiveMatch( OSDictionary * matching, bool changesOK = false); 1732 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1733 void startMatching( IOOptionBits options = 0 ); 1734 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1735 void doServiceMatch( IOOptionBits options ); 1736 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1737 void doServiceTerminate( IOOptionBits options ); 1738 1739 bool hasParent(IOService * root); 1740 static void setRootMedia(IOService * root); 1741 static void publishHiddenMedia(IOService * parent); 1742 static bool publishHiddenMediaApplier(const OSObject * entry, void * context); 1743 bool canTerminateForReplacement(IOService * client); 1744 void unregisterAllInterrupts(void); 1745 1746 private: 1747 1748 bool matchPassive(OSDictionary * table, uint32_t options); 1749 bool matchInternal(OSDictionary * table, uint32_t options, unsigned int * did); 1750 static bool instanceMatch(const OSObject * entry, void * context); 1751 OSDictionary * _copyPropertiesForMatching(void); 1752 1753 static OSPtr<OSObject> copyExistingServices( OSDictionary * matching, 1754 IOOptionBits inState, IOOptionBits options = 0 ); 1755 1756 static OSPtr<IONotifier> setNotification( 1757 const OSSymbol * type, OSDictionary * matching, 1758 IOServiceMatchingNotificationHandler handler, 1759 void * target, void * ref, 1760 SInt32 priority = 0 ); 1761 1762 static OSPtr<IONotifier> doInstallNotification( 1763 const OSSymbol * type, OSDictionary * matching, 1764 IOServiceMatchingNotificationHandler handler, 1765 void * target, void * ref, 1766 SInt32 priority, OSIterator ** existing ); 1767 1768 static bool syncNotificationHandler( void * target, void * ref, 1769 IOService * newService, IONotifier * notifier ); 1770 1771 static void userServerCheckInTokenCancellationHandler( 1772 IOUserServerCheckInToken * token, 1773 void * ref); 1774 1775 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1776 void deliverNotification( const OSSymbol * type, 1777 IOOptionBits orNewState, IOOptionBits andNewState ); 1778 1779 OSPtr<OSArray> copyNotifiers(const OSSymbol * type, 1780 IOOptionBits orNewState, IOOptionBits andNewState); 1781 1782 bool invokeNotifiers(OSArray * willSend[]); 1783 bool invokeNotifier( class _IOServiceNotifier * notify ); 1784 1785 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1786 void unregisterAllInterest( void ); 1787 1788 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1789 IOReturn waitForState( UInt32 mask, UInt32 value, 1790 mach_timespec_t * timeout = NULL ); 1791 1792 IOReturn waitForState( UInt32 mask, UInt32 value, uint64_t timeout ); 1793 1794 UInt32 _adjustBusy(SInt32 delta); 1795 UInt32 _adjustBusy(SInt32 delta, bool unlock); 1796 1797 bool terminatePhase1( IOOptionBits options = 0 ); 1798 void scheduleTerminatePhase2( IOOptionBits options = 0 ); 1799 void scheduleStop( IOService * provider ); 1800 1801 static void waitToBecomeTerminateThread( void ); 1802 static void __attribute__((__noreturn__)) terminateThread( void * arg, wait_result_t unused ); 1803 static void terminateWorker( IOOptionBits options ); 1804 static void actionWillTerminate( IOService * victim, IOOptionBits options, 1805 OSArray * doPhase2List, bool, void * ); 1806 static void actionDidTerminate( IOService * victim, IOOptionBits options, 1807 void *, void *, void *); 1808 1809 static void actionWillStop( IOService * victim, IOOptionBits options, 1810 void *, void *, void *); 1811 static void actionDidStop( IOService * victim, IOOptionBits options, 1812 void *, void *, void *); 1813 1814 static void actionFinalize( IOService * victim, IOOptionBits options, 1815 void *, void *, void *); 1816 static void actionStop( IOService * client, IOService * provider, 1817 void *, void *, void *); 1818 1819 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1820 IOReturn resolveInterrupt(IOService *nub, int source); 1821 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1822 IOReturn lookupInterrupt( 1823 int source, bool resolve, 1824 LIBKERN_RETURNS_NOT_RETAINED IOInterruptController * 1825 *interruptController); 1826 1827 #ifdef XNU_KERNEL_PRIVATE 1828 /* end xnu internals */ 1829 #endif 1830 1831 /* power management */ 1832 public: 1833 1834 /*! @function PMinit 1835 * @abstract Initializes power management for a driver. 1836 * @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. 1837 * Most calls to <code>PMinit</code> are followed by calls to @link joinPMtree joinPMtree@/link and @link registerPowerDriver registerPowerDriver@/link. */ 1838 1839 virtual void PMinit( void ); 1840 1841 /*! @function PMstop 1842 * @abstract Stop power managing the driver. 1843 * @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. 1844 * 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. */ 1845 1846 virtual void PMstop( void ); 1847 1848 /*! @function joinPMtree 1849 * @abstract Joins the driver into the power plane of the I/O Registry. 1850 * @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). 1851 * 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. 1852 * @param driver The driver to be added to the power plane, usually <code>this</code>. */ 1853 1854 virtual void joinPMtree( IOService * driver ); 1855 1856 /*! @function registerPowerDriver 1857 * @abstract Registers a set of power states that the driver supports. 1858 * @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. 1859 * 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. 1860 * @param controllingDriver A pointer to the calling driver, usually <code>this</code>. 1861 * @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>. 1862 * @param numberOfStates The number of power states in the array. 1863 * @result <code>IOPMNoErr</code>. All errors are logged via <code>kprintf</code>. */ 1864 1865 virtual IOReturn registerPowerDriver( 1866 IOService * controllingDriver, 1867 IOPMPowerState * powerStates, 1868 unsigned long numberOfStates ); 1869 1870 /*! @function registerInterestedDriver 1871 * @abstract Allows an IOService object to register interest in the changing power state of a power-managed IOService object. 1872 * @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. 1873 * The interested driver is retained until the power interest is removed by calling <code>deRegisterInterestedDriver</code>. 1874 * The interested driver should override @link powerStateWillChangeTo powerStateWillChangeTo@/link and @link powerStateDidChangeTo powerStateDidChangeTo@/link to receive these power change messages. 1875 * 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. 1876 * @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. 1877 * @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). */ 1878 1879 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1880 IOPMPowerFlags registerInterestedDriver( IOService * theDriver ); 1881 1882 /*! @function deRegisterInterestedDriver 1883 * @abstract De-registers power state interest from a previous call to <code>registerInterestedDriver</code>. 1884 * @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. 1885 * Most drivers do not need to override <code>deRegisterInterestedDriver</code>. 1886 * @param theDriver The interested driver previously passed into @link registerInterestedDriver registerInterestedDriver@/link. 1887 * @result A return code that can be ignored by the caller. */ 1888 1889 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1890 IOReturn deRegisterInterestedDriver( IOService * theDriver ); 1891 1892 /*! @function acknowledgePowerChange 1893 * @abstract Acknowledges an in-progress power state change. 1894 * @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>. 1895 * 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>. 1896 * @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. 1897 * @result <code>IOPMNoErr</code>. */ 1898 1899 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1900 IOReturn acknowledgePowerChange( IOService * whichDriver ); 1901 1902 /*! @function acknowledgeSetPowerState 1903 * @abstract Acknowledges the belated completion of a driver's <code>setPowerState</code> power state change. 1904 * @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>. 1905 * Any driver that does not return <code>kIOPMAckImplied</code> from its <code>setPowerState</code> implementation must later call <code>acknowledgeSetPowerState</code>. 1906 * @result <code>IOPMNoErr</code>. */ 1907 1908 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1909 IOReturn acknowledgeSetPowerState( void ); 1910 1911 /*! @function requestPowerDomainState 1912 * @abstract Tells a driver to adjust its power state. 1913 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 1914 1915 virtual IOReturn requestPowerDomainState( 1916 IOPMPowerFlags desiredState, 1917 IOPowerConnection * whichChild, 1918 unsigned long specificationFlags ); 1919 1920 /*! @function makeUsable 1921 * @abstract Requests that a device become usable. 1922 * @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. 1923 * <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. 1924 * @result A return code that can be ignored by the caller. */ 1925 1926 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1927 IOReturn makeUsable( void ); 1928 1929 /*! @function temporaryPowerClampOn 1930 * @abstract A driver calls this method to hold itself in the highest power state until it has children. 1931 * @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. 1932 * @result A return code that can be ignored by the caller. */ 1933 1934 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1935 IOReturn temporaryPowerClampOn( void ); 1936 1937 /*! @function changePowerStateTo 1938 * @abstract Sets a driver's power state. 1939 * @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. 1940 * 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: 1941 * <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. 1942 * <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> 1943 * @param ordinal The number of the desired power state in the power state array. 1944 * @result A return code that can be ignored by the caller. */ 1945 1946 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1947 IOReturn changePowerStateTo( unsigned long ordinal ); 1948 1949 /*! @function currentCapability 1950 * @abstract Finds out the capability of a device's current power state. 1951 * @result A copy of the <code>capabilityFlags</code> field for the current power state in the power state array. */ 1952 1953 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1954 IOPMPowerFlags currentCapability( void ); 1955 1956 /*! @function currentPowerConsumption 1957 * @abstract Finds out the current power consumption of a device. 1958 * @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. 1959 * @result A copy of the <code>staticPower</code> field for the current power state in the power state array. */ 1960 1961 APPLE_KEXT_COMPATIBILITY_VIRTUAL 1962 unsigned long currentPowerConsumption( void ); 1963 1964 /*! @function activityTickle 1965 * @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. 1966 * @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. 1967 * 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. 1968 * 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. 1969 * 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. 1970 * @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. 1971 * @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. 1972 * @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. */ 1973 1974 virtual bool activityTickle( 1975 unsigned long type, 1976 unsigned long stateNumber = 0 ); 1977 1978 /*! @function setAggressiveness 1979 * @abstract Broadcasts an aggressiveness factor from the parent of a driver to the driver. 1980 * @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. 1981 * A driver that has joined the power plane via @link joinPMtree joinPMtree@/link will receive <code>setAgressiveness</code> calls when aggressiveness factors change. 1982 * 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. 1983 * Most drivers do not need to implement <code>setAgressiveness</code>. 1984 * @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>.) 1985 * @param newLevel The aggressiveness factor's new value. 1986 * @result <code>IOPMNoErr</code>. */ 1987 1988 virtual IOReturn setAggressiveness( 1989 unsigned long type, 1990 unsigned long newLevel ); 1991 1992 /*! @function getAggressiveness 1993 * @abstract Returns the current aggressiveness value for the given type. 1994 * @param type The aggressiveness factor to query. 1995 * @param currentLevel Upon successful return, contains the value of aggressiveness factor <code>type</code>. 1996 * @result <code>kIOReturnSuccess</code> upon success; an I/O Kit error code otherwise. */ 1997 1998 virtual IOReturn getAggressiveness( 1999 unsigned long type, 2000 unsigned long * currentLevel ); 2001 2002 #ifndef __LP64__ 2003 /*! @function systemWake 2004 * @abstract Tells every driver in the power plane that the system is waking up. 2005 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2006 2007 virtual IOReturn systemWake( void ) 2008 APPLE_KEXT_DEPRECATED; 2009 2010 /*! @function temperatureCriticalForZone 2011 * @abstract Alerts a driver to a critical temperature in some thermal zone. 2012 * @discussion This call is unused by power management. It is not intended to be called or overridden. */ 2013 2014 virtual IOReturn temperatureCriticalForZone( IOService * whichZone ) 2015 APPLE_KEXT_DEPRECATED; 2016 2017 /*! @function youAreRoot 2018 * @abstract Informs power management which IOService object is the power plane root. 2019 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2020 2021 virtual IOReturn youAreRoot( void ) 2022 APPLE_KEXT_DEPRECATED; 2023 2024 /*! @function setPowerParent 2025 * @abstract This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2026 2027 virtual IOReturn setPowerParent( 2028 IOPowerConnection * parent, 2029 bool stateKnown, 2030 IOPMPowerFlags currentState ) 2031 APPLE_KEXT_DEPRECATED; 2032 #endif /* !__LP64__ */ 2033 2034 /*! @function addPowerChild 2035 * @abstract Informs a driver that it has a new child. 2036 * @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. 2037 * @param theChild A pointer to the child IOService object. */ 2038 2039 virtual IOReturn addPowerChild( IOService * theChild ); 2040 2041 /*! @function removePowerChild 2042 * @abstract Informs a power managed driver that one of its power plane childen is disappearing. 2043 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2044 2045 virtual IOReturn removePowerChild( IOPowerConnection * theChild ); 2046 2047 #ifndef __LP64__ 2048 /*! @function command_received 2049 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2050 2051 virtual void command_received( void *, void *, void *, void * ); 2052 #endif 2053 2054 /*! @function start_PM_idle_timer 2055 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2056 2057 APPLE_KEXT_COMPATIBILITY_VIRTUAL 2058 void start_PM_idle_timer( void ); 2059 2060 #ifndef __LP64__ 2061 /*! @function PM_idle_timer_expiration 2062 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2063 2064 virtual void PM_idle_timer_expiration( void ) 2065 APPLE_KEXT_DEPRECATED; 2066 2067 /*! @function PM_Clamp_Timer_Expired 2068 * @discussion This call is handled internally by power management. It is not intended to be overridden or called by drivers. */ 2069 2070 virtual void PM_Clamp_Timer_Expired( void ) 2071 APPLE_KEXT_DEPRECATED; 2072 #endif 2073 2074 /*! @function setIdleTimerPeriod 2075 * @abstract Sets or changes the idle timer period. 2076 * @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. 2077 * @param period The desired idle timer period in seconds. 2078 * @result <code>kIOReturnSuccess</code> upon success; an I/O Kit error code otherwise. */ 2079 2080 virtual IOReturn setIdleTimerPeriod( unsigned long period ); 2081 2082 #ifndef __LP64__ 2083 /*! @function getPMworkloop 2084 * @abstract Returns a pointer to the system-wide power management work loop. 2085 * @availability Deprecated in Mac OS X version 10.6. 2086 * @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. */ 2087 2088 virtual IOWorkLoop * getPMworkloop( void ) 2089 APPLE_KEXT_DEPRECATED; 2090 #endif 2091 2092 /*! @function getPowerState 2093 * @abstract Determines a device's power state. 2094 * @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. 2095 * @result The current power state's index into the device's power state array. */ 2096 2097 UInt32 getPowerState( void ); 2098 2099 /*! @function setPowerState 2100 * @abstract Requests a power managed driver to change the power state of its device. 2101 * @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. 2102 * 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. 2103 * @param powerStateOrdinal The number in the power state array of the state the driver is being instructed to switch to. 2104 * @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. 2105 * @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. */ 2106 2107 virtual IOReturn setPowerState( 2108 unsigned long powerStateOrdinal, 2109 IOService * whatDevice ); 2110 2111 #ifndef __LP64__ 2112 /*! @function clampPowerOn 2113 * @abstract Deprecated. Do not use. */ 2114 2115 virtual void clampPowerOn( unsigned long duration ); 2116 #endif 2117 2118 /*! @function maxCapabilityForDomainState 2119 * @abstract Determines a driver's highest power state possible for a given power domain state. 2120 * @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. 2121 * 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. 2122 * @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. 2123 * @result A state number. */ 2124 2125 virtual unsigned long maxCapabilityForDomainState( IOPMPowerFlags domainState ); 2126 2127 /*! @function initialPowerStateForDomainState 2128 * @abstract Determines which power state a device is in, given the current power domain state. 2129 * @discussion Power management calls this method once, when the driver is initializing power management. 2130 * 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. 2131 * @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. 2132 * @result A state number. */ 2133 2134 virtual unsigned long initialPowerStateForDomainState( IOPMPowerFlags domainState ); 2135 2136 /*! @function powerStateForDomainState 2137 * @abstract Determines what power state the device would be in for a given power domain state. 2138 * @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. 2139 * @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. 2140 * @result A state number. */ 2141 2142 virtual unsigned long powerStateForDomainState( IOPMPowerFlags domainState ); 2143 2144 /*! @function powerStateWillChangeTo 2145 * @abstract Informs interested parties that a device is about to change its power state. 2146 * @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. 2147 * <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. 2148 * @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). 2149 * @param stateNumber The number of the state in the state array that the device is switching to. 2150 * @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. 2151 * @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. */ 2152 2153 virtual IOReturn powerStateWillChangeTo( 2154 IOPMPowerFlags capabilities, 2155 unsigned long stateNumber, 2156 IOService * whatDevice ); 2157 2158 /*! @function powerStateDidChangeTo 2159 * @abstract Informs interested parties that a device has changed to a different power state. 2160 * @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. 2161 * <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. 2162 * @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). 2163 * @param stateNumber The number of the state in the state array that the device is switching to. 2164 * @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. 2165 * @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. */ 2166 2167 virtual IOReturn powerStateDidChangeTo( 2168 IOPMPowerFlags capabilities, 2169 unsigned long stateNumber, 2170 IOService * whatDevice ); 2171 2172 #ifndef __LP64__ 2173 /*! @function didYouWakeSystem 2174 * @abstract Asks a driver if its device is the one that just woke the system from sleep. 2175 * @availability Deprecated in Mac OS X version 10.6. 2176 * @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. 2177 * @result <code>true</code> if the driver's device woke the system and <code>false</code> otherwise. */ 2178 2179 virtual bool didYouWakeSystem( void ) 2180 APPLE_KEXT_DEPRECATED; 2181 2182 /*! @function newTemperature 2183 * @abstract Tells a power managed driver that the temperature in the thermal zone has changed. 2184 * @discussion This call is unused by power management. It is not intended to be called or overridden. */ 2185 2186 virtual IOReturn newTemperature( long currentTemp, IOService * whichZone ) 2187 APPLE_KEXT_DEPRECATED; 2188 #endif 2189 2190 virtual bool askChangeDown( unsigned long ); 2191 virtual bool tellChangeDown( unsigned long ); 2192 virtual void tellNoChangeDown( unsigned long ); 2193 virtual void tellChangeUp( unsigned long ); 2194 virtual IOReturn allowPowerChange( unsigned long refcon ); 2195 virtual IOReturn cancelPowerChange( unsigned long refcon ); 2196 2197 protected: 2198 /*! @function changePowerStateToPriv 2199 * @abstract Tells a driver's superclass to change the power state of its device. 2200 * @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. 2201 * 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. 2202 * 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. 2203 * @param ordinal The number of the desired power state in the power state array. 2204 * @result A return code that can be ignored by the caller. */ 2205 public: 2206 IOReturn changePowerStateToPriv( unsigned long ordinal ); 2207 2208 /*! @function powerOverrideOnPriv 2209 * @abstract Allows a driver to ignore its children's power management requests and only use changePowerStateToPriv to define its own power state. 2210 * @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. 2211 * @result A return code that can be ignored by the caller. */ 2212 2213 IOReturn powerOverrideOnPriv( void ); 2214 2215 /*! @function powerOverrideOffPriv 2216 * @abstract Allows a driver to disable a power override. 2217 * @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. 2218 * @result A return code that can be ignored by the caller. */ 2219 2220 IOReturn powerOverrideOffPriv( void ); 2221 2222 /*! @function powerChangeDone 2223 * @abstract Tells a driver when a power state change is complete. 2224 * @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. 2225 * @param stateNumber The number of the state in the state array that the device has switched from. */ 2226 2227 virtual void powerChangeDone( unsigned long stateNumber ); 2228 #ifdef XNU_KERNEL_PRIVATE 2229 /* Power management internals */ 2230 public: 2231 void idleTimerExpired( void ); 2232 void settleTimerExpired( void ); 2233 IOReturn synchronizePowerTree( IOOptionBits options = 0, IOService * notifyRoot = NULL ); 2234 bool assertPMDriverCall( IOPMDriverCallEntry * callEntry, IOOptionBits method, const IOPMinformee * inform = NULL, IOOptionBits options = 0 ); 2235 void deassertPMDriverCall( IOPMDriverCallEntry * callEntry ); 2236 IOReturn changePowerStateWithOverrideTo( IOPMPowerStateIndex ordinal, IOPMRequestTag tag ); 2237 IOReturn changePowerStateWithTagToPriv( IOPMPowerStateIndex ordinal, IOPMRequestTag tag ); 2238 IOReturn changePowerStateWithTagTo( IOPMPowerStateIndex ordinal, IOPMRequestTag tag ); 2239 IOReturn changePowerStateForRootDomain( IOPMPowerStateIndex ordinal ); 2240 IOReturn setIgnoreIdleTimer( bool ignore ); 2241 IOReturn quiescePowerTree( void * target, IOPMCompletionAction action, void * param ); 2242 IOPMPowerStateIndex getPowerStateForClient( const OSSymbol * client ); 2243 static const char * getIOMessageString( uint32_t msg ); 2244 static void setAdvisoryTickleEnable( bool enable ); 2245 void reset_watchdog_timer(IOService *obj, int timeout); 2246 void reset_watchdog_timer(int timeout = 0); 2247 void start_watchdog_timer( void ); 2248 void stop_watchdog_timer( void ); 2249 void start_watchdog_timer(uint64_t deadline); 2250 IOReturn registerInterestForNotifier( IONotifier *notify, const OSSymbol * typeOfInterest, 2251 IOServiceInterestHandler handler, void * target, void * ref ); 2252 2253 static IOWorkLoop * getIOPMWorkloop( void ); 2254 bool getBlockingDriverCall(thread_t *thread, const void **callMethod); 2255 void cancelIdlePowerDown(IOService * service); 2256 void cancelIdlePowerDownSync( void ); 2257 2258 protected: 2259 bool tellClientsWithResponse( int messageType ); 2260 void tellClients( int messageType ); 2261 void PMDebug( uint32_t event, uintptr_t param1, uintptr_t param2 ); 2262 2263 private: 2264 #ifndef __LP64__ 2265 void ack_timer_ticked( void ); 2266 IOReturn serializedAllowPowerChange2( unsigned long ); 2267 IOReturn serializedCancelPowerChange2( unsigned long ); 2268 IOReturn powerDomainWillChangeTo( IOPMPowerFlags, IOPowerConnection * ); 2269 IOReturn powerDomainDidChangeTo( IOPMPowerFlags, IOPowerConnection * ); 2270 #endif 2271 static void allocPMInitLock( void ); 2272 void PMfree( void ); 2273 bool tellChangeDown1( unsigned long ); 2274 bool tellChangeDown2( unsigned long ); 2275 IOReturn startPowerChange( IOPMPowerChangeFlags, IOPMPowerStateIndex, IOPMPowerFlags, IOPowerConnection *, IOPMPowerFlags ); 2276 void setParentInfo( IOPMPowerFlags, IOPowerConnection *, bool ); 2277 IOReturn notifyAll( uint32_t nextMS ); 2278 bool notifyChild( IOPowerConnection * child ); 2279 IOPMPowerStateIndex getPowerStateForDomainFlags( IOPMPowerFlags flags ); 2280 2281 // power change initiated by driver 2282 void OurChangeStart( void ); 2283 void OurSyncStart( void ); 2284 void OurChangeTellClientsPowerDown( void ); 2285 void OurChangeTellUserPMPolicyPowerDown( void ); 2286 void OurChangeTellPriorityClientsPowerDown( void ); 2287 void OurChangeTellCapabilityWillChange( void ); 2288 void OurChangeNotifyInterestedDriversWillChange( void ); 2289 void OurChangeSetPowerState( void ); 2290 void OurChangeWaitForPowerSettle( void ); 2291 void OurChangeNotifyInterestedDriversDidChange( void ); 2292 void OurChangeTellCapabilityDidChange( void ); 2293 void OurChangeFinish( void ); 2294 2295 // downward power change initiated by a power parent 2296 IOReturn ParentChangeStart( void ); 2297 void ParentChangeTellPriorityClientsPowerDown( void ); 2298 void ParentChangeTellCapabilityWillChange( void ); 2299 void ParentChangeNotifyInterestedDriversWillChange( void ); 2300 void ParentChangeSetPowerState( void ); 2301 void ParentChangeWaitForPowerSettle( void ); 2302 void ParentChangeNotifyInterestedDriversDidChange( void ); 2303 void ParentChangeTellCapabilityDidChange( void ); 2304 void ParentChangeAcknowledgePowerChange( void ); 2305 void ParentChangeRootChangeDown( void ); 2306 2307 void all_done( void ); 2308 void start_ack_timer( void ); 2309 void stop_ack_timer( void ); 2310 void start_ack_timer( UInt32 value, UInt32 scale ); 2311 void startSettleTimer( void ); 2312 void start_spindump_timer( const char * delay_type ); 2313 void stop_spindump_timer( void ); 2314 bool checkForDone( void ); 2315 bool responseValid( uint32_t x, int pid ); 2316 void updateClientResponses( void ); 2317 void computeDesiredState( unsigned long tempDesire, bool computeOnly ); 2318 void trackSystemSleepPreventers( IOPMPowerStateIndex, IOPMPowerStateIndex, IOPMPowerChangeFlags ); 2319 void tellSystemCapabilityChange( uint32_t nextMS ); 2320 void restartIdleTimer( void ); 2321 void startDriverCalloutTimer( void ); 2322 void stopDriverCalloutTimer( void ); 2323 2324 static void ack_timer_expired( thread_call_param_t, thread_call_param_t ); 2325 static void watchdog_timer_expired( thread_call_param_t arg0, thread_call_param_t arg1 ); 2326 static void spindump_timer_expired( thread_call_param_t arg0, thread_call_param_t arg1 ); 2327 static IOReturn actionAckTimerExpired(OSObject *, void *, void *, void *, void * ); 2328 static IOReturn actionSpinDumpTimerExpired(OSObject *, void *, void *, void *, void * ); 2329 2330 static IOReturn actionDriverCalloutDone(OSObject *, void *, void *, void *, void * ); 2331 static IOPMRequest * acquirePMRequest( IOService * target, IOOptionBits type, IOPMRequest * active = NULL ); 2332 static void releasePMRequest( IOPMRequest * request ); 2333 static void pmDriverCallout( IOService * from, thread_call_param_t ); 2334 static void pmDriverCalloutTimer( thread_call_param_t, thread_call_param_t ); 2335 static void pmTellAppWithResponse( OSObject * object, void * context ); 2336 static void pmTellClientWithResponse( OSObject * object, void * context ); 2337 static void pmTellCapabilityAppWithResponse( OSObject * object, void * arg ); 2338 static void pmTellCapabilityClientWithResponse( OSObject * object, void * arg ); 2339 static void submitPMRequest(LIBKERN_CONSUMED IOPMRequest * request ); 2340 static void submitPMRequests( IOPMRequest * requests[], IOItemCount count ); 2341 bool ackTimerTick( void ); 2342 void addPowerChild1( IOPMRequest * request ); 2343 void addPowerChild2( IOPMRequest * request ); 2344 void addPowerChild3( IOPMRequest * request ); 2345 void adjustPowerState( IOPMPowerStateIndex clamp = 0 ); 2346 void handlePMstop( IOPMRequest * request ); 2347 void handleRegisterPowerDriver( IOPMRequest * request ); 2348 bool handleAcknowledgePowerChange( IOPMRequest * request ); 2349 bool handleAcknowledgeSetPowerState( IOPMRequest * request ); 2350 bool handleCancelIdlePowerDown( void ); 2351 void handlePowerDomainWillChangeTo( IOPMRequest * request ); 2352 void handlePowerDomainDidChangeTo( IOPMRequest * request ); 2353 void handleRequestPowerState( IOPMRequest * request ); 2354 void handlePowerOverrideChanged( IOPMRequest * request ); 2355 bool _activityTickle( unsigned long type, unsigned long stateNumber ); 2356 void handleDeferredActivityTickle( IOPMRequest * request ); 2357 void handleActivityTickle( IOPMRequest * request ); 2358 void handleInterestChanged( IOPMRequest * request ); 2359 void handleSynchronizePowerTree( IOPMRequest * request ); 2360 void executePMRequest( IOPMRequest * request ); 2361 bool actionPMWorkQueueInvoke( IOPMRequest * request, IOPMWorkQueue * queue ); 2362 bool actionPMWorkQueueRetire( IOPMRequest * request, IOPMWorkQueue * queue ); 2363 bool actionPMRequestQueue( IOPMRequest * request, IOPMRequestQueue * queue ); 2364 bool actionPMReplyQueue( IOPMRequest * request, IOPMRequestQueue * queue ); 2365 bool actionPMCompletionQueue( LIBKERN_CONSUMED IOPMRequest * request, IOPMCompletionQueue * queue ); 2366 bool notifyInterestedDrivers( void ); 2367 void notifyInterestedDriversDone( void ); 2368 bool notifyControllingDriver( void ); 2369 void notifyControllingDriverDone( void ); 2370 void driverSetPowerState( void ); 2371 void driverInformPowerChange( void ); 2372 unsigned long driverMaxCapabilityForDomainState( IOPMPowerFlags domainState ); 2373 unsigned long driverInitialPowerStateForDomainState( IOPMPowerFlags domainState ); 2374 bool isPMBlocked( IOPMRequest * request, int count ); 2375 void notifyChildren( void ); 2376 void notifyChildrenOrdered( void ); 2377 void notifyChildrenDelayed( void ); 2378 void notifyRootDomain( void ); 2379 void notifyRootDomainDone( void ); 2380 void cleanClientResponses( bool logErrors ); 2381 void updatePowerClient( const OSSymbol * client, IOPMPowerStateIndex powerState ); 2382 void removePowerClient( const OSSymbol * client ); 2383 IOReturn requestPowerState( const OSSymbol * client, IOPMPowerStateIndex state, IOPMRequestTag tag = 0 ); 2384 IOReturn requestDomainPower( IOPMPowerStateIndex ourPowerState, IOOptionBits options = 0 ); 2385 IOReturn configurePowerStatesReport( IOReportConfigureAction action, void *result ); 2386 IOReturn updatePowerStatesReport( IOReportConfigureAction action, void *result, void *destination ); 2387 IOReturn configureSimplePowerReport(IOReportConfigureAction action, void *result ); 2388 IOReturn updateSimplePowerReport( IOReportConfigureAction action, void *result, void *destination ); 2389 void waitForPMDriverCall( IOService * target = NULL ); 2390 2391 friend class IOUserServer; 2392 #endif /* XNU_KERNEL_PRIVATE */ 2393 }; 2394 2395 #ifdef PRIVATE 2396 2397 class IOServiceCompatibility : public IOService 2398 { 2399 OSDeclareDefaultStructors(IOServiceCompatibility); 2400 }; 2401 2402 #endif /* PRIVATE */ 2403 2404 #endif /* ! _IOKIT_IOSERVICE_H */ 2405