iokit/IOKit/pwr_mgt/RootDomain.h

   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 #ifndef _IOKIT_ROOTDOMAIN_H
  29 #define _IOKIT_ROOTDOMAIN_H
  30
  31 #include <libkern/c++/OSPtr.h>
  32 #include <IOKit/IOService.h>
  33 #include <IOKit/pwr_mgt/IOPM.h>
  34 #include <IOKit/IOBufferMemoryDescriptor.h>
  35 #include <sys/vnode.h>
  36
  37 #ifdef XNU_KERNEL_PRIVATE
  38
  39 #include <IOKit/pwr_mgt/IOPMPrivate.h>
  40
  41 struct AggressivesRecord;
  42 struct IOPMMessageFilterContext;
  43 struct IOPMActions;
  44 struct IOPMSystemSleepParameters;
  45 class PMSettingObject;
  46 class PMTraceWorker;
  47 class IOPMPowerStateQueue;
  48 class RootDomainUserClient;
  49 class PMAssertionsTracker;
  50 class IOTimerEventSource;
  51
  52 #define OBFUSCATE(x) (void *)VM_KERNEL_UNSLIDE_OR_PERM(x)
  53
  54 #endif
  55
  56 /*!
  57  * Types for PM Assertions
  58  * For creating, releasing, and getting PM assertion levels.
  59  */
  60
  61 /*! IOPMDriverAssertionType
  62  * A bitfield describing a set of assertions. May be used to specify which assertions
  63  * to set with <link>IOPMrootDomain::createPMAssertion</link>; or to query which
  64  * assertions are set with <link>IOPMrootDomain::releasePMAssertion</link>.
  65  */
  66 typedef uint64_t IOPMDriverAssertionType;
  67
  68 /* IOPMDriverAssertionID
  69  * Drivers may create PM assertions to request system behavior (keep the system awake,
  70  *  or keep the display awake). When a driver creates an assertion via
  71  *  <link>IOPMrootDomain::createPMAssertion</link>, PM returns a handle to
  72  *  the assertion of type IOPMDriverAssertionID.
  73  */
  74 typedef uint64_t IOPMDriverAssertionID;
  75 #define kIOPMUndefinedDriverAssertionID       0
  76
  77 /* IOPMDriverAssertionLevel
  78  * Possible values for IOPMDriverAssertionLevel are <link>kIOPMDriverAssertionLevelOff</link>
  79  * and <link>kIOPMDriverAssertionLevelOn</link>
  80  */
  81 typedef uint32_t IOPMDriverAssertionLevel;
  82 #define kIOPMDriverAssertionLevelOff          0
  83 #define kIOPMDriverAssertionLevelOn           255
  84
  85 /*
  86  * Flags for get/setSleepSupported()
  87  */
  88 enum {
  89         kRootDomainSleepNotSupported    = 0x00000000,
  90         kRootDomainSleepSupported         = 0x00000001,
  91         kFrameBufferDeepSleepSupported    = 0x00000002,
  92         kPCICantSleep                   = 0x00000004
  93 };
  94
  95 /*
  96  * IOPMrootDomain registry property keys
  97  */
  98 #define kRootDomainSupportedFeatures        "Supported Features"
  99 #define kRootDomainSleepReasonKey           "Last Sleep Reason"
 100 #define kRootDomainSleepOptionsKey          "Last Sleep Options"
 101 #define kIOPMRootDomainWakeReasonKey        "Wake Reason"
 102 #define kIOPMRootDomainWakeTypeKey          "Wake Type"
 103 #define kIOPMRootDomainPowerStatusKey       "Power Status"
 104
 105 /*
 106  * Possible sleep reasons found under kRootDomainSleepReasonsKey
 107  */
 108 #define kIOPMClamshellSleepKey              "Clamshell Sleep"
 109 #define kIOPMPowerButtonSleepKey            "Power Button Sleep"
 110 #define kIOPMSoftwareSleepKey               "Software Sleep"
 111 #define kIOPMOSSwitchHibernationKey         "OS Switch Sleep"
 112 #define kIOPMIdleSleepKey                   "Idle Sleep"
 113 #define kIOPMLowPowerSleepKey               "Low Power Sleep"
 114 #define kIOPMThermalEmergencySleepKey       "Thermal Emergency Sleep"
 115 #define kIOPMMaintenanceSleepKey            "Maintenance Sleep"
 116
 117 /*
 118  * String constants for communication with PM CPU
 119  */
 120 #define kIOPMRootDomainLidCloseCString      "LidClose"
 121 #define kIOPMRootDomainBatPowerCString      "BatPower"
 122
 123 /*
 124  * Supported Feature bitfields for IOPMrootDomain::publishFeature()
 125  */
 126 enum {
 127         kIOPMSupportedOnAC      = (1 << 0),
 128         kIOPMSupportedOnBatt    = (1 << 1),
 129         kIOPMSupportedOnUPS     = (1 << 2)
 130 };
 131
 132 typedef IOReturn (*IOPMSettingControllerCallback)
 133 (OSObject *target, const OSSymbol *type,
 134     OSObject *val, uintptr_t refcon);
 135
 136 __BEGIN_DECLS
 137 IONotifier *    registerSleepWakeInterest(
 138         IOServiceInterestHandler, void *, void * = NULL);
 139
 140 IONotifier *    registerPrioritySleepWakeInterest(
 141         IOServiceInterestHandler handler,
 142         void * self, void * ref = NULL);
 143
 144 IOReturn        acknowledgeSleepWakeNotification(void * );
 145
 146 IOReturn        vetoSleepWakeNotification(void * PMrefcon);
 147 __END_DECLS
 148
 149 #define IOPM_ROOTDOMAIN_REV        2
 150
 151 class IOPMrootDomain : public IOService
 152 {
 153         OSDeclareFinalStructors(IOPMrootDomain);
 154
 155 public:
 156         static IOPMrootDomain * construct( void );
 157
 158         virtual bool        start( IOService * provider ) APPLE_KEXT_OVERRIDE;
 159         virtual IOReturn    setAggressiveness( unsigned long, unsigned long ) APPLE_KEXT_OVERRIDE;
 160         virtual IOReturn    getAggressiveness( unsigned long, unsigned long * ) APPLE_KEXT_OVERRIDE;
 161
 162         virtual IOReturn    sleepSystem( void );
 163         IOReturn            sleepSystemOptions( OSDictionary *options );
 164
 165         virtual IOReturn    setProperties( OSObject * ) APPLE_KEXT_OVERRIDE;
 166         virtual bool        serializeProperties( OSSerialize * s ) const APPLE_KEXT_OVERRIDE;
 167         virtual OSPtr<OSObject>  copyProperty( const char * aKey ) const APPLE_KEXT_OVERRIDE;
 168
 169 /*! @function systemPowerEventOccurred
 170  *    @abstract Other drivers may inform IOPMrootDomain of system PM events
 171  *    @discussion systemPowerEventOccurred is a richer alternative to receivePowerNotification()
 172  *        Only Apple-owned kexts should have reason to call systemPowerEventOccurred.
 173  *    @param event An OSSymbol describing the type of power event.
 174  *    @param intValue A 32-bit integer value associated with the event.
 175  *    @result kIOReturnSuccess on success */
 176
 177         IOReturn            systemPowerEventOccurred(
 178                 const OSSymbol *event,
 179                 uint32_t intValue );
 180
 181         IOReturn            systemPowerEventOccurred(
 182                 const OSSymbol *event,
 183                 OSObject *value );
 184
 185 #ifdef XNU_KERNEL_PRIVATE   // Hide doc from public headers
 186 /*! @function claimSystemWakeEvent
 187  *   @abstract   Apple-internal SPI to describe system wake events.
 188  *   @discussion IOKit drivers may call claimSystemWakeEvent() during system wakeup to
 189  *               provide human readable debug information describing the event(s) that
 190  *               caused the system to wake.
 191  *
 192  *               - Drivers should call claimSystemWakeEvent before completing
 193  *                 their setPowerState() acknowledgement. IOPMrootDomain stops
 194  *                 collecting wake events when driver wake is complete.
 195  *
 196  *               - It is only appropriate to claim a wake event when the driver
 197  *                 can positively identify its hardware has generated an event
 198  *                 that can wake the system.
 199  *
 200  *               - This call tracks wake events from a non-S0 state (S0i, S3, S4) into S0.
 201  *               - This call does not track wake events from DarkWake(S0) to FullWake(S0).
 202  *
 203  *       Examples:
 204  *               (reason  = "WiFi.TCPData",
 205  *        details = "TCPKeepAlive packet arrived from IP 16.2.1.1")
 206  *               (reason  = "WiFi.ScanOffload",
 207  *        details = "WiFi station 'AppleWiFi' signal dropped below threshold")
 208  *               (reason  = "Enet.LinkToggle",
 209  *        details = "Ethernet attached")
 210  *
 211  *   @param device   The device/nub that is associated with the wake event.
 212  *
 213  *   @param flags    Pass kIOPMWakeEventSource if the device is the source
 214  *                   of the wake event. Pass zero if the device is forwarding or
 215  *                   aggregating wake events from multiple sources, e.g. an USB or
 216  *                   Thunderbolt host controller.
 217  *
 218  *   @param reason   Caller should pass a human readable C string describing the
 219  *                   wake reason. Please use a string from the list below, or create
 220  *                   your own string matching this format:
 221  *                             [Hardware].[Event]
 222  *                             WiFi.MagicPacket
 223  *                             WiFi.ScanOffload
 224  *                             WiFi.mDNSConflict
 225  *                             WiFi.mDNSService
 226  *                             WiFi.TCPData
 227  *                             WiFi.TCPTimeout
 228  *                             WiFi.FirmwareCrash
 229  *                             Enet.MagicPacket
 230  *                             Enet.mDNSConflict
 231  *                             Enet.mDNSService
 232  *                             Enet.TCPData
 233  *                             Enet.TCPTimeout
 234  *                             Enet.Service
 235  *                             Enet.LinkToggle
 236  *                             Enet.ConflictResolution
 237  *                             Enet.PatternMatch
 238  *                             Enet.Timer
 239  *                             Enet.LinkUpTimeout
 240  *                             Enet.LinkDown
 241  *                             USB.DeviceAttach
 242  *                             USB.DeviceDetach
 243  *
 244  *    @param details Optional details further describing the wake event.
 245  *                   Please pass an OSString defining the event.
 246  */
 247 #endif
 248         void                claimSystemWakeEvent(
 249                 IOService     *device,
 250                 IOOptionBits  flags,
 251                 const char    *reason,
 252                 OSObject      *details = NULL );
 253
 254         void                claimSystemBootEvent(
 255                 IOService     *device,
 256                 IOOptionBits  flags,
 257                 const char    *reason,
 258                 OSObject      *details = NULL );
 259
 260         void                claimSystemShutdownEvent(
 261                 IOService     *device,
 262                 IOOptionBits  flags,
 263                 const char    *reason,
 264                 OSObject      *details = NULL );
 265
 266         virtual IOReturn    receivePowerNotification( UInt32 msg );
 267
 268         virtual void        setSleepSupported( IOOptionBits flags );
 269
 270         virtual IOOptionBits getSleepSupported( void );
 271
 272         void                wakeFromDoze( void );
 273
 274         void                requestUserActive(IOService *driver, const char *reason);
 275
 276 // KEXT driver announces support of power management feature
 277
 278         void                publishFeature( const char *feature );
 279
 280 // KEXT driver announces support of power management feature
 281 // And specifies power sources with kIOPMSupportedOn{AC/Batt/UPS} bitfield.
 282 // Returns a unique uint32_t identifier for later removing support for this
 283 // feature.
 284 // NULL is acceptable for uniqueFeatureID for kexts without plans to unload.
 285
 286         void                publishFeature( const char *feature,
 287             uint32_t supportedWhere,
 288             uint32_t *uniqueFeatureID);
 289
 290 // KEXT driver announces removal of a previously published power management
 291 // feature. Pass 'uniqueFeatureID' returned from publishFeature()
 292
 293         IOReturn            removePublishedFeature( uint32_t removeFeatureID );
 294
 295 /*! @function copyPMSetting
 296  *   @abstract Copy the current value for a PM setting. Returns an OSNumber or
 297  *       OSData depending on the setting.
 298  *   @param whichSetting Name of the desired setting.
 299  *   @result OSObject value if valid, NULL otherwise. */
 300
 301         OSPtr<OSObject>           copyPMSetting( OSSymbol *whichSetting );
 302
 303 /*! @function registerPMSettingController
 304  *   @abstract Register for callbacks on changes to certain PM settings.
 305  *   @param settings NULL terminated array of C strings, each string for a PM
 306  *       setting that the caller is interested in and wants to get callbacks for.
 307  *   @param callout C function ptr or member function cast as such.
 308  *   @param target The target of the callback, usually 'this'
 309  *   @param refcon Will be passed to caller in callback; for caller's use.
 310  *   @param handle Caller should keep the OSObject * returned here. If non-NULL,
 311  *       handle will have a retain count of 1 on return. To deregister, pass to
 312  *       unregisterPMSettingController()
 313  *   @result kIOReturnSuccess on success. */
 314
 315         IOReturn            registerPMSettingController(
 316                 const OSSymbol *settings[],
 317                 IOPMSettingControllerCallback callout,
 318                 OSObject   *target,
 319                 uintptr_t  refcon,
 320                 OSObject   **handle);                     // out param
 321
 322 /*! @function registerPMSettingController
 323  *   @abstract Register for callbacks on changes to certain PM settings.
 324  *   @param settings NULL terminated array of C strings, each string for a PM
 325  *       setting that the caller is interested in and wants to get callbacks for.
 326  *   @param supportedPowerSources bitfield indicating which power sources these
 327  *       settings are supported for (kIOPMSupportedOnAC, etc.)
 328  *   @param callout C function ptr or member function cast as such.
 329  *   @param target The target of the callback, usually 'this'
 330  *   @param refcon Will be passed to caller in callback; for caller's use.
 331  *   @param handle Caller should keep the OSObject * returned here. If non-NULL,
 332  *       handle will have a retain count of 1 on return. To deregister, pass to
 333  *       unregisterPMSettingController()
 334  *   @result kIOReturnSuccess on success. */
 335
 336         IOReturn            registerPMSettingController(
 337                 const OSSymbol *settings[],
 338                 uint32_t   supportedPowerSources,
 339                 IOPMSettingControllerCallback callout,
 340                 OSObject   *target,
 341                 uintptr_t  refcon,
 342                 OSObject   **handle);                     // out param
 343
 344         virtual OSPtr<IONotifier> registerInterest(
 345                 const OSSymbol * typeOfInterest,
 346                 IOServiceInterestHandler handler,
 347                 void * target, void * ref = NULL ) APPLE_KEXT_OVERRIDE;
 348
 349         virtual IOReturn    callPlatformFunction(
 350                 const OSSymbol *functionName,
 351                 bool waitForFunction,
 352                 void *param1, void *param2,
 353                 void *param3, void *param4 ) APPLE_KEXT_OVERRIDE;
 354
 355 /*! @function createPMAssertion
 356  *   @abstract Creates an assertion to influence system power behavior.
 357  *   @param whichAssertionsBits A bitfield specify the assertion that the caller requests.
 358  *   @param assertionLevel An integer detailing the initial assertion level, kIOPMDriverAssertionLevelOn
 359  *       or kIOPMDriverAssertionLevelOff.
 360  *   @param ownerService A pointer to the caller's IOService class, for tracking.
 361  *   @param ownerDescription A reverse-DNS string describing the caller's identity and reason.
 362  *   @result On success, returns a new assertion of type IOPMDriverAssertionID
 363  */
 364         IOPMDriverAssertionID createPMAssertion(
 365                 IOPMDriverAssertionType whichAssertionsBits,
 366                 IOPMDriverAssertionLevel assertionLevel,
 367                 IOService *ownerService,
 368                 const char *ownerDescription);
 369
 370 /* @function setPMAssertionLevel
 371  *  @abstract Modify the level of a pre-existing assertion.
 372  *  @discussion Change the value of a PM assertion to influence system behavior,
 373  *   without undergoing the work required to create or destroy an assertion. Suggested
 374  *   for clients who will assert and de-assert needs for PM behavior several times over
 375  *   their lifespan.
 376  *  @param assertionID An assertion ID previously returned by <link>createPMAssertion</link>
 377  *  @param assertionLevel The new assertion level.
 378  *  @result kIOReturnSuccess if it worked; kIOReturnNotFound or other IOReturn error on failure.
 379  */
 380         IOReturn setPMAssertionLevel(IOPMDriverAssertionID assertionID, IOPMDriverAssertionLevel assertionLevel);
 381
 382 /*! @function getPMAssertionLevel
 383  *   @absract Returns the active level of the specified assertion(s).
 384  *   @discussion Returns <link>kIOPMDriverAssertionLevelOff</link> or
 385  *       <link>kIOPMDriverAssertionLevelOn</link>. If multiple assertions are specified
 386  *       in the bitfield, only returns <link>kIOPMDriverAssertionLevelOn</link>
 387  *       if all assertions are active.
 388  *   @param whichAssertionBits Bits defining the assertion or assertions the caller is interested in
 389  *       the level of. If in doubt, pass <link>kIOPMDriverAssertionCPUBit</link> as the argument.
 390  *   @result Returns <link>kIOPMDriverAssertionLevelOff</link> or
 391  *       <link>kIOPMDriverAssertionLevelOn</link> indicating the specified assertion's levels, if available.
 392  *       If the assertions aren't supported on this machine, or aren't recognized by the OS, the
 393  *       result is undefined.
 394  */
 395         IOPMDriverAssertionLevel getPMAssertionLevel(IOPMDriverAssertionType whichAssertionBits);
 396
 397 /*! @function releasePMAssertion
 398  *   @abstract Removes an assertion to influence system power behavior.
 399  *   @result On success, returns a new assertion of type IOPMDriverAssertionID *
 400  */
 401         IOReturn releasePMAssertion(IOPMDriverAssertionID releaseAssertion);
 402
 403 /*! @function restartWithStackshot
 404  *   @abstract Take a stackshot of the system and restart the system.
 405  *   @result Return kIOReturnSuccess if it work, kIOReturnError if the service is not available.
 406  */
 407         IOReturn restartWithStackshot();
 408
 409         IOReturn    setWakeTime(uint64_t wakeContinuousTime);
 410
 411 private:
 412         unsigned long getRUN_STATE(void);
 413
 414         virtual IOReturn    changePowerStateTo( unsigned long ordinal ) APPLE_KEXT_COMPATIBILITY_OVERRIDE;
 415         virtual IOReturn    changePowerStateToPriv( unsigned long ordinal );
 416         virtual IOReturn    requestPowerDomainState( IOPMPowerFlags, IOPowerConnection *, unsigned long ) APPLE_KEXT_OVERRIDE;
 417         virtual void        powerChangeDone( unsigned long ) APPLE_KEXT_OVERRIDE;
 418         virtual bool        tellChangeDown( unsigned long ) APPLE_KEXT_OVERRIDE;
 419         virtual bool        askChangeDown( unsigned long ) APPLE_KEXT_OVERRIDE;
 420         virtual void        tellChangeUp( unsigned long ) APPLE_KEXT_OVERRIDE;
 421         virtual void        tellNoChangeDown( unsigned long ) APPLE_KEXT_OVERRIDE;
 422         virtual IOReturn configureReport(IOReportChannelList   *channels,
 423             IOReportConfigureAction action,
 424             void                    *result,
 425             void                    *destination) APPLE_KEXT_OVERRIDE;
 426         virtual IOReturn updateReport(IOReportChannelList      *channels,
 427             IOReportUpdateAction     action,
 428             void                     *result,
 429             void                     *destination) APPLE_KEXT_OVERRIDE;
 430
 431         void             configureReportGated(uint64_t channel_id,
 432             uint64_t action,
 433             void     *result);
 434         IOReturn         updateReportGated(uint64_t ch_id,
 435             void *result,
 436             IOBufferMemoryDescriptor *dest);
 437
 438 #ifdef XNU_KERNEL_PRIVATE
 439 /* Root Domain internals */
 440 public:
 441         void        tagPowerPlaneService(
 442                 IOService *             service,
 443                 IOPMActions *           actions,
 444                 IOPMPowerStateIndex     maxPowerState );
 445
 446         void        overrideOurPowerChange(
 447                 IOService *             service,
 448                 IOPMActions *           actions,
 449                 const IOPMRequest *     request,
 450                 IOPMPowerStateIndex *   inOutPowerState,
 451                 IOPMPowerChangeFlags *  inOutChangeFlags );
 452
 453         void        handleOurPowerChangeStart(
 454                 IOService *             service,
 455                 IOPMActions *           actions,
 456                 const IOPMRequest *     request,
 457                 IOPMPowerStateIndex     powerState,
 458                 IOPMPowerChangeFlags *  inOutChangeFlags );
 459
 460         void        handleOurPowerChangeDone(
 461                 IOService *             service,
 462                 IOPMActions *           actions,
 463                 const IOPMRequest *     request,
 464                 IOPMPowerStateIndex     powerState,
 465                 IOPMPowerChangeFlags    changeFlags );
 466
 467         void        overridePowerChangeForService(
 468                 IOService *             service,
 469                 IOPMActions *           actions,
 470                 const IOPMRequest *     request,
 471                 IOPMPowerStateIndex *   inOutPowerState,
 472                 IOPMPowerChangeFlags *  inOutChangeFlags );
 473
 474         void        handleActivityTickleForDisplayWrangler(
 475                 IOService *             service,
 476                 IOPMActions *           actions );
 477
 478         void        handleUpdatePowerClientForDisplayWrangler(
 479                 IOService *             service,
 480                 IOPMActions *           actions,
 481                 const OSSymbol *        powerClient,
 482                 IOPMPowerStateIndex     oldPowerState,
 483                 IOPMPowerStateIndex     newPowerState );
 484
 485         bool        shouldDelayChildNotification(
 486                 IOService *     service );
 487
 488         void        handlePowerChangeStartForPCIDevice(
 489                 IOService *             service,
 490                 IOPMActions *           actions,
 491                 const IOPMRequest *     request,
 492                 IOPMPowerStateIndex     powerState,
 493                 IOPMPowerChangeFlags *  inOutChangeFlags );
 494
 495         void        handlePowerChangeDoneForPCIDevice(
 496                 IOService *             service,
 497                 IOPMActions *           actions,
 498                 const IOPMRequest *     request,
 499                 IOPMPowerStateIndex     powerState,
 500                 IOPMPowerChangeFlags    changeFlags );
 501
 502         void        askChangeDownDone(
 503                 IOPMPowerChangeFlags * inOutChangeFlags,
 504                 bool * cancel );
 505
 506         void        handlePublishSleepWakeUUID(
 507                 bool shouldPublish);
 508
 509         void        handleQueueSleepWakeUUID(
 510                 OSObject *obj);
 511
 512         void        willTellSystemCapabilityDidChange(void);
 513
 514         void        handleSetDisplayPowerOn(bool powerOn);
 515
 516         void        willNotifyPowerChildren( IOPMPowerStateIndex newPowerState );
 517
 518         IOReturn    setMaintenanceWakeCalendar(
 519                 const IOPMCalendarStruct * calendar );
 520
 521         IOReturn    getSystemSleepType(uint32_t * sleepType, uint32_t * standbyTimer);
 522
 523 // Handle callbacks from IOService::systemWillShutdown()
 524         void        acknowledgeSystemWillShutdown( IOService * from );
 525
 526 // Handle platform halt and restart notifications
 527         void        handlePlatformHaltRestart( UInt32 pe_type );
 528
 529         IOReturn    shutdownSystem( void );
 530         IOReturn    restartSystem( void );
 531         void        handleSleepTimerExpiration( void );
 532
 533         bool        activitySinceSleep(void);
 534         bool        abortHibernation(void);
 535         void        updateConsoleUsers(void);
 536
 537         IOReturn    joinAggressiveness( IOService * service );
 538         void        handleAggressivesRequests( void );
 539
 540         void        kdebugTrace(uint32_t event, uint64_t regId,
 541             uintptr_t param1, uintptr_t param2, uintptr_t param3 = 0);
 542         void        tracePoint(uint8_t point);
 543         void        traceDetail(uint32_t msgType, uint32_t msgIndex, uint32_t delay);
 544         void        traceNotification(OSObject *notifier, bool start, uint64_t ts = 0, uint32_t msgIndex = UINT_MAX);
 545         void        traceNotificationAck(OSObject *notifier, uint32_t delay_ms);
 546         void        traceNotificationResponse(OSObject *object, uint32_t delay_ms, uint32_t ack_time_us);
 547         void        traceFilteredNotification(OSObject *notifier);
 548         const char * getNotificationClientName(OSObject *notifier);
 549
 550         void        startSpinDump(uint32_t spindumpKind);
 551
 552         bool        systemMessageFilter(
 553                 void * object, void * arg1, void * arg2, void * arg3 );
 554
 555         bool        updatePreventIdleSleepList(
 556                 IOService * service, bool addNotRemove );
 557         void        updatePreventSystemSleepList(
 558                 IOService * service, bool addNotRemove );
 559
 560         bool        updatePreventIdleSleepListInternal(
 561                 IOService * service, bool addNotRemove, unsigned int oldCount);
 562         unsigned int idleSleepPreventersCount();
 563
 564         void        publishPMSetting(
 565                 const OSSymbol * feature, uint32_t where, uint32_t * featureID );
 566
 567         void        pmStatsRecordEvent(
 568                 int             eventIndex,
 569                 AbsoluteTime    timestamp);
 570
 571         void        pmStatsRecordApplicationResponse(
 572                 const OSSymbol      *response,
 573                 const char          *name,
 574                 int                 messageType,
 575                 uint32_t            delay_ms,
 576                 uint64_t            id,
 577                 OSObject            *object,
 578                 IOPMPowerStateIndex ps = 0,
 579                 bool                async = false);
 580
 581         void        copyWakeReasonString( char * outBuf, size_t bufSize );
 582         void        copyShutdownReasonString( char * outBuf, size_t bufSize );
 583         void        lowLatencyAudioNotify(uint64_t time, boolean_t state);
 584
 585 #if HIBERNATION
 586         bool        getHibernateSettings(
 587                 uint32_t *  hibernateMode,
 588                 uint32_t *  hibernateFreeRatio,
 589                 uint32_t *  hibernateFreeTime );
 590         bool        mustHibernate( void );
 591 #endif
 592         void        takeStackshot(bool restart);
 593         void        sleepWakeDebugTrig(bool restart);
 594         void        sleepWakeDebugEnableWdog();
 595         bool        sleepWakeDebugIsWdogEnabled();
 596         void        sleepWakeDebugSaveSpinDumpFile();
 597         bool        checkShutdownTimeout();
 598         void        panicWithShutdownLog(uint32_t timeoutInMs) __abortlike;
 599         uint32_t    getWatchdogTimeout();
 600         void        deleteStackshot();
 601
 602 private:
 603         friend class PMSettingObject;
 604         friend class RootDomainUserClient;
 605         friend class PMAssertionsTracker;
 606
 607         static IOReturn sysPowerDownHandler( void * target, void * refCon,
 608             UInt32 messageType, IOService * service,
 609             void * messageArgument, vm_size_t argSize );
 610
 611         static IOReturn displayWranglerNotification( void * target, void * refCon,
 612             UInt32 messageType, IOService * service,
 613             void * messageArgument, vm_size_t argSize );
 614
 615         static IOReturn rootBusyStateChangeHandler( void * target, void * refCon,
 616             UInt32 messageType, IOService * service,
 617             void * messageArgument, vm_size_t argSize );
 618
 619         void initializeBootSessionUUID( void );
 620
 621         void fullWakeDelayedWork( void );
 622
 623         OSPtr<IOService>        wrangler;
 624         OSPtr<OSDictionary>     wranglerIdleSettings;
 625
 626         IOLock                  *featuresDictLock;// guards supportedFeatures
 627         IOLock                  *wakeEventLock;
 628         IOPMPowerStateQueue     *pmPowerStateQueue;
 629
 630         OSPtr<OSArray>           allowedPMSettings;
 631         OSPtr<OSArray>           noPublishPMSettings;
 632         OSPtr<PMTraceWorker>     pmTracer;
 633         PMAssertionsTracker     *pmAssertions;
 634
 635 // Settings controller info
 636         IOLock                  *settingsCtrlLock;
 637         OSPtr<OSDictionary>      settingsCallbacks;
 638         OSPtr<OSDictionary>      fPMSettingsDict;
 639
 640 // Statistics
 641         OSPtr<const OSSymbol>   _statsNameKey;
 642         OSPtr<const OSSymbol>   _statsPIDKey;
 643         OSPtr<const OSSymbol>   _statsTimeMSKey;
 644         OSPtr<const OSSymbol>   _statsResponseTypeKey;
 645         OSPtr<const OSSymbol>   _statsMessageTypeKey;
 646         OSPtr<const OSSymbol>   _statsPowerCapsKey;
 647         uint32_t                sleepCnt;
 648         uint32_t                darkWakeCnt;
 649         uint32_t                displayWakeCnt;
 650
 651         OSPtr<OSString>         queuedSleepWakeUUIDString;
 652         OSPtr<OSArray>          pmStatsAppResponses;
 653         IOLock                  *pmStatsLock;// guards pmStatsAppResponses
 654
 655         void                    *sleepDelaysReport; // report to track time taken to go to sleep
 656         uint32_t                sleepDelaysClientCnt;// Number of interested clients in sleepDelaysReport
 657         uint64_t                ts_sleepStart;
 658         uint64_t                wake2DarkwakeDelay;  // Time taken to change from full wake -> Dark wake
 659
 660         void                    *assertOnWakeReport;// report to track time spent without any assertions held after wake
 661         uint32_t                assertOnWakeClientCnt;// Number of clients interested in assertOnWakeReport
 662         clock_sec_t             assertOnWakeSecs;   // Num of secs after wake for first assertion
 663
 664         bool                    uuidPublished;
 665
 666 // Pref: idle time before idle sleep
 667         bool                    idleSleepEnabled;
 668         uint32_t                sleepSlider;
 669         uint32_t                idleSeconds;
 670
 671 // Difference between sleepSlider and longestNonSleepSlider
 672         uint32_t                extraSleepDelay;
 673
 674 // Used to wait between say display idle and system idle
 675         thread_call_t           extraSleepTimer;
 676         thread_call_t           powerButtonDown;
 677         thread_call_t           powerButtonUp;
 678         thread_call_t           diskSyncCalloutEntry;
 679         thread_call_t           fullWakeThreadCall;
 680         thread_call_t           updateConsoleUsersEntry;
 681
 682 // Track system capabilities.
 683         uint32_t                _desiredCapability;
 684         uint32_t                _currentCapability;
 685         uint32_t                _pendingCapability;
 686         uint32_t                _highestCapability;
 687         OSPtr<OSSet>            _joinedCapabilityClients;
 688         uint32_t                _systemStateGeneration;
 689
 690 // Type of clients that can receive system messages.
 691         enum {
 692                 kSystemMessageClientPowerd    = 0x01,
 693                 kSystemMessageClientLegacyApp = 0x02,
 694                 kSystemMessageClientKernel    = 0x04,
 695                 kSystemMessageClientAll       = 0x07
 696         };
 697         uint32_t                _systemMessageClientMask;
 698
 699 // Power state and capability change transitions.
 700         enum {
 701                 kSystemTransitionNone         = 0,
 702                 kSystemTransitionSleep        = 1,
 703                 kSystemTransitionWake         = 2,
 704                 kSystemTransitionCapability   = 3,
 705                 kSystemTransitionNewCapClient = 4
 706         }                       _systemTransitionType;
 707
 708         unsigned int            systemBooting           :1;
 709         unsigned int            systemShutdown          :1;
 710         unsigned int            systemDarkWake          :1;
 711         unsigned int            clamshellExists         :1;
 712         unsigned int            clamshellClosed         :1;
 713         unsigned int            clamshellDisabled       :1;
 714         unsigned int            desktopMode             :1;
 715         unsigned int            acAdaptorConnected      :1;
 716
 717         unsigned int            clamshellIgnoreClose    :1;
 718         unsigned int            idleSleepTimerPending   :1;
 719         unsigned int            userDisabledAllSleep    :1;
 720         unsigned int            ignoreTellChangeDown    :1;
 721         unsigned int            wranglerAsleep          :1;
 722         unsigned int            darkWakeExit            :1;
 723         unsigned int            _preventUserActive      :1;
 724         unsigned int            darkWakePowerClamped    :1;
 725
 726         unsigned int            capabilityLoss          :1;
 727         unsigned int            pciCantSleepFlag        :1;
 728         unsigned int            pciCantSleepValid       :1;
 729         unsigned int            darkWakeLogClamp        :1;
 730         unsigned int            darkWakeToSleepASAP     :1;
 731         unsigned int            darkWakeMaintenance     :1;
 732         unsigned int            darkWakeSleepService    :1;
 733         unsigned int            darkWakePostTickle      :1;
 734
 735         unsigned int            sleepTimerMaintenance   :1;
 736         unsigned int            sleepToStandby          :1;
 737         unsigned int            lowBatteryCondition     :1;
 738         unsigned int            hibernateDisabled       :1;
 739         unsigned int            hibernateRetry          :1;
 740         unsigned int            wranglerTickled         :1;
 741         unsigned int            userIsActive            :1;
 742         unsigned int            userWasActive           :1;
 743
 744         unsigned int            displayIdleForDemandSleep :1;
 745         unsigned int            darkWakeHibernateError  :1;
 746         unsigned int            thermalWarningState     :1;
 747         unsigned int            toldPowerdCapWillChange :1;
 748         unsigned int            displayPowerOnRequested :1;
 749         unsigned int            isRTCAlarmWake          :1;
 750         unsigned int            wranglerPowerOff        :1;
 751         unsigned int            thermalEmergencyState   :1;
 752
 753         uint8_t                 tasksSuspended;
 754         uint8_t                 tasksSuspendState;
 755         uint32_t                hibernateMode;
 756         AbsoluteTime            userActivityTime;
 757         AbsoluteTime            userActivityTime_prev;
 758         uint32_t                userActivityCount;
 759         uint32_t                userActivityAtSleep;
 760         uint32_t                lastSleepReason;
 761         uint32_t                fullToDarkReason;
 762         uint32_t                hibernateAborted;
 763         uint8_t                 standbyNixed;
 764         uint8_t                 resetTimers;
 765
 766         enum FullWakeReason {
 767                 kFullWakeReasonNone = 0,
 768                 kFullWakeReasonLocalUser = 1,
 769                 kFullWakeReasonDisplayOn = 2,
 770                 fFullWakeReasonDisplayOnAndLocalUser = 3
 771         };
 772         uint32_t                fullWakeReason;
 773
 774         enum {
 775                 kClamshellSleepDisableInternal = 0x01,
 776                 kClamshellSleepDisablePowerd   = 0x02
 777         };
 778         uint32_t                clamshellSleepDisableMask;
 779
 780 // Info for communicating system state changes to PMCPU
 781         int32_t                 idxPMCPUClamshell;
 782         int32_t                 idxPMCPULimitedPower;
 783
 784         IOOptionBits            platformSleepSupport;
 785         uint32_t                _debugWakeSeconds;
 786
 787         queue_head_t            aggressivesQueue;
 788         thread_call_t           aggressivesThreadCall;
 789         OSPtr<OSData>                aggressivesData;
 790
 791         AbsoluteTime            userBecameInactiveTime;
 792
 793 // PCI top-level PM trace
 794         OSPtr<IOService>        pciHostBridgeDevice;
 795         OSPtr<IOService>        pciHostBridgeDriver;
 796
 797         OSPtr<IONotifier>       systemCapabilityNotifier;
 798
 799         typedef struct {
 800                 uint32_t            pid;
 801                 uint32_t            refcount;
 802         } PMNotifySuspendedStruct;
 803
 804         uint32_t                pmSuspendedCapacity;
 805         uint32_t                pmSuspendedSize;
 806         PMNotifySuspendedStruct *pmSuspendedPIDS;
 807
 808         OSPtr<OSSet>            preventIdleSleepList;
 809         OSPtr<OSSet>            preventSystemSleepList;
 810
 811         OSPtr<const OSSymbol>   _nextScheduledAlarmType;
 812         clock_sec_t             _nextScheduledAlarmUTC;
 813         clock_sec_t             _calendarWakeAlarmUTC;
 814         UInt32                  _scheduledAlarmMask;
 815         UInt32                  _userScheduledAlarmMask;
 816
 817 #if HIBERNATION
 818         clock_sec_t             _standbyTimerResetSeconds;
 819 #endif
 820         volatile uint32_t   swd_lock;/* Lock to access swd_buffer & and its header */
 821         void  *             swd_buffer;/* Memory allocated for dumping sleep/wake logs */
 822         uint32_t            swd_flags;/* Flags defined in IOPMPrivate.h */
 823         void *              swd_compressed_buffer;
 824         void  *             swd_spindump_buffer;
 825         thread_t            notifierThread;
 826         OSPtr<OSObject>     notifierObject;
 827
 828         OSPtr<IOBufferMemoryDescriptor>    swd_spindump_memDesc;
 829         OSPtr<IOBufferMemoryDescriptor>    swd_memDesc;
 830
 831 // Wake Event Reporting
 832         OSPtr<OSArray>       _systemWakeEventsArray;
 833         bool                 _acceptSystemWakeEvents;
 834
 835         // AOT --
 836         IOPMCalendarStruct   _aotWakeTimeCalendar;
 837         OSPtr<IOTimerEventSource> _aotTimerES;
 838         clock_sec_t          _aotWakeTimeUTC;
 839         uint64_t             _aotTestTime;
 840         uint64_t             _aotTestInterval;
 841         uint32_t             _aotPendingFlags;
 842 public:
 843         IOPMAOTMetrics     * _aotMetrics;
 844         uint8_t              _aotMode;
 845 private:
 846         uint8_t              _aotNow;
 847         uint8_t              _aotTasksSuspended;
 848         uint8_t              _aotExit;
 849         uint8_t              _aotTimerScheduled;
 850         uint8_t              _aotReadyToFullWake;
 851         uint64_t             _aotLastWakeTime;
 852         uint64_t             _aotWakeTimeContinuous;
 853         uint64_t             _aotWakePreWindow;
 854         uint64_t             _aotWakePostWindow;
 855         uint64_t             _aotLingerTime;
 856
 857         bool        aotShouldExit(bool checkTimeSet, bool software);
 858         void        aotExit(bool cps);
 859         void        aotEvaluate(IOTimerEventSource * timer);
 860 public:
 861         bool        isAOTMode(void);
 862 private:
 863         // -- AOT
 864
 865         void        updateTasksSuspend(void);
 866         int         findSuspendedPID(uint32_t pid, uint32_t *outRefCount);
 867
 868 // IOPMrootDomain internal sleep call
 869         IOReturn    privateSleepSystem( uint32_t sleepReason );
 870         void        reportUserInput( void );
 871         void        updateUserActivity( void );
 872         void        setDisableClamShellSleep( bool );
 873         void        setClamShellSleepDisable(bool disable, uint32_t bitmask);
 874         bool        checkSystemSleepAllowed( IOOptionBits options,
 875             uint32_t sleepReason );
 876         bool        checkSystemSleepEnabled( void );
 877         bool        checkSystemCanSleep( uint32_t sleepReason );
 878         bool        checkSystemCanSustainFullWake( void );
 879
 880         void        adjustPowerState( bool sleepASAP = false );
 881         void        setQuickSpinDownTimeout( void );
 882         void        restoreUserSpinDownTimeout( void );
 883
 884         bool        shouldSleepOnClamshellClosed(void );
 885         bool        shouldSleepOnRTCAlarmWake(void );
 886         void        sendClientClamshellNotification( void );
 887
 888 // Inform PMCPU of changes to state like lid, AC vs. battery
 889         void        informCPUStateChange( uint32_t type, uint32_t value );
 890
 891         void        dispatchPowerEvent( uint32_t event, void * arg0, uint64_t arg1 );
 892         void        handlePowerNotification( UInt32 msg );
 893
 894         IOReturn    setPMSetting(const OSSymbol *, OSObject *);
 895
 896         void        startIdleSleepTimer( uint32_t inSeconds );
 897         void        cancelIdleSleepTimer( void );
 898         uint32_t    getTimeToIdleSleep( void );
 899
 900         IOReturn    setAggressiveness(
 901                 unsigned long type,
 902                 unsigned long value,
 903                 IOOptionBits  options );
 904
 905         void        synchronizeAggressives(
 906                 queue_head_t * services,
 907                 const AggressivesRecord * array,
 908                 int count );
 909
 910         void        broadcastAggressives(
 911                 const AggressivesRecord * array,
 912                 int count );
 913
 914         IOReturn    setPMAssertionUserLevels(IOPMDriverAssertionType);
 915
 916         void        publishSleepWakeUUID( bool shouldPublish );
 917
 918         void        evaluatePolicy( int stimulus, uint32_t arg = 0 );
 919         void        requestFullWake( FullWakeReason reason );
 920         void        willEnterFullWake( void );
 921
 922         void        evaluateAssertions(IOPMDriverAssertionType newAssertions,
 923             IOPMDriverAssertionType oldAssertions);
 924
 925         void        deregisterPMSettingObject( PMSettingObject * pmso );
 926
 927         uint32_t    checkForValidDebugData(const char *fname, vfs_context_t *ctx,
 928             void *tmpBuf, struct vnode **vp);
 929         void        getFailureData(thread_t *thread, char *failureStr, size_t strLen);
 930         void        saveFailureData2File();
 931         void        tracePhase2String(uint32_t tracePhase, const char **phaseString, const char **description);
 932         void        sleepWakeDebugMemAlloc();
 933         void        sleepWakeDebugSpinDumpMemAlloc();
 934         errno_t     sleepWakeDebugSaveFile(const char *name, char *buf, int len);
 935
 936         IOReturn    changePowerStateWithOverrideTo( IOPMPowerStateIndex ordinal, IOPMRequestTag tag );
 937         IOReturn    changePowerStateWithTagToPriv( IOPMPowerStateIndex ordinal, IOPMRequestTag tag );
 938         IOReturn    changePowerStateWithTagTo( IOPMPowerStateIndex ordinal, IOPMRequestTag tag );
 939
 940 #if HIBERNATION
 941         bool        getSleepOption( const char * key, uint32_t * option );
 942         bool        evaluateSystemSleepPolicy( IOPMSystemSleepParameters * p,
 943             int phase, uint32_t * hibMode );
 944         void        evaluateSystemSleepPolicyEarly( void );
 945         void        evaluateSystemSleepPolicyFinal( void );
 946 #endif /* HIBERNATION */
 947
 948         bool        latchDisplayWranglerTickle( bool latch );
 949         void        setDisplayPowerOn( uint32_t options );
 950
 951         void        acceptSystemWakeEvents( uint32_t control );
 952         void        systemDidNotSleep( void );
 953         void        preventTransitionToUserActive( bool prevent );
 954         void        setThermalState(OSObject *value);
 955         void        copySleepPreventersList(OSArray  **idleSleepList, OSArray  **systemSleepList);
 956         void        copySleepPreventersListWithID(OSArray  **idleSleepList, OSArray  **systemSleepList);
 957         void        recordRTCAlarm(const OSSymbol *type, OSObject *object);
 958
 959         // Used to inform interested clients about low latency audio activity in the system
 960         OSPtr<OSDictionary>   lowLatencyAudioNotifierDict;
 961         OSPtr<OSNumber>       lowLatencyAudioNotifyStateVal;
 962         OSPtr<OSNumber>       lowLatencyAudioNotifyTimestampVal;
 963         OSPtr<const OSSymbol> lowLatencyAudioNotifyStateSym;
 964         OSPtr<const OSSymbol> lowLatencyAudioNotifyTimestampSym;
 965 #endif /* XNU_KERNEL_PRIVATE */
 966 };
 967
 968 #ifdef XNU_KERNEL_PRIVATE
 969 class IORootParent : public IOService
 970 {
 971         OSDeclareFinalStructors(IORootParent);
 972
 973 public:
 974         static void initialize( void );
 975         virtual OSPtr<OSObject> copyProperty( const char * aKey ) const APPLE_KEXT_OVERRIDE;
 976         bool start( IOService * nub ) APPLE_KEXT_OVERRIDE;
 977         void shutDownSystem( void );
 978         void restartSystem( void );
 979         void sleepSystem( void );
 980         void dozeSystem( void );
 981         void sleepToDoze( void );
 982         void wakeSystem( void );
 983 };
 984 #endif /* XNU_KERNEL_PRIVATE */
 985
 986 #endif /* _IOKIT_ROOTDOMAIN_H */