iokit/IOKit/pwr_mgt/IOPMPrivate.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, 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_IOPMPRIVATE_H
  29 #define _IOKIT_IOPMPRIVATE_H
  30
  31 #include <IOKit/pwr_mgt/IOPM.h>
  32
  33 /* @constant kIOPMEventTypeIntermediateFlag
  34  * @abstract This bit indicates the event is an intermediate event
  35  *      which must occur within a major system power event.
  36  */
  37 #define kIOPMEventTypeIntermediateFlag              0x10000000
  38
  39 /* @enum SystemEventTypes
  40  * @abstract Potential system events logged in the system event record.
  41  */
  42 enum {
  43     kIOPMEventTypeUndefined                     = 0,
  44
  45     /* Event types mark driver events
  46      */
  47     kIOPMEventTypeSetPowerStateImmediate        = 1001,
  48     kIOPMEventTypeSetPowerStateDelayed          = 1002,
  49     kIOPMEventTypePSWillChangeTo                = 1003,
  50     kIOPMEventTypePSDidChangeTo                 = 1004,
  51     kIOPMEventTypeAppResponse                   = 1005,
  52
  53
  54     /* Start and stop event types bracket major
  55      * system power management events.
  56      */
  57     kIOPMEventTypeSleep                         = 2001,
  58     kIOPMEventTypeSleepDone                     = 2002,
  59     kIOPMEventTypeWake                          = 3001,
  60     kIOPMEventTypeWakeDone                      = 3002,
  61     kIOPMEventTypeDoze                          = 4001,
  62     kIOPMEventTypeDozeDone                      = 4002,
  63     kIOPMEventTypeUUIDSet                       = 6001,
  64     kIOPMEventTypeUUIDClear                     = 6002,
  65
  66     /* Intermediate events that may only occur within the bounds
  67      * of a major system event (between the event's initiation and its "done event".)
  68      * e.g. chronologically kIOPMEventTypeSleep may be followed by one or more
  69      *      intermediate events, which then must be followed by kIOPMEventTypeSleepDone.
  70      *
  71      * The intermediate events below will always occur in a Sleep or Wake event, and may
  72      *      or may not occur for any of the other events.
  73      */
  74     kIOPMEventTypeAppNotificationsFinished      = 501 | kIOPMEventTypeIntermediateFlag,
  75     kIOPMEventTypeDriverNotificationsFinished   = 502 | kIOPMEventTypeIntermediateFlag,
  76     kIOPMEventTypeCalTimeChange                 = 503 | kIOPMEventTypeIntermediateFlag
  77 };
  78
  79 /*****************************************************************************
  80  *
  81  * Private Root Domain general interest messages
  82  *
  83  * Check IOPM.h when adding new messages to avoid conflict.
  84  *
  85  *****************************************************************************/
  86
  87 /* kIOPMMessageUserIsActiveChanged
  88  * User became active or inactive. Message sent after the kIOPMUserIsActiveKey
  89  * property was updated with a new value.
  90  */
  91 #define kIOPMMessageUserIsActiveChanged \
  92                 iokit_family_msg(sub_iokit_powermanagement, 0x400)
  93
  94 /*
  95  * Private IOMessage notifications shared between kernel and userspace PM policy
  96  */
  97 #define kIOPMMessageLastCallBeforeSleep \
  98                 iokit_family_msg(sub_iokit_powermanagement, 0x410)
  99
 100 #define kIOPMMessageIdleSleepPreventers \
 101                 iokit_family_msg(sub_iokit_powermanagement, 0x420)
 102
 103 #define kIOPMMessageSystemSleepPreventers \
 104                 iokit_family_msg(sub_iokit_powermanagement, 0x430)
 105
 106 /* @enum SystemSleepReasons
 107  * @abstract The potential causes for system sleep as logged in the system event record.
 108  */
 109 enum {
 110     kIOPMSleepReasonClamshell                   = 101,
 111     kIOPMSleepReasonPowerButton                 = 102,
 112     kIOPMSleepReasonSoftware                    = 103,
 113     kIOPMSleepReasonOSSwitchHibernate           = 104,
 114     kIOPMSleepReasonIdle                        = 105,
 115     kIOPMSleepReasonLowPower                    = 106,
 116     kIOPMSleepReasonThermalEmergency            = 107,
 117     kIOPMSleepReasonMaintenance                 = 108,
 118     kIOPMSleepReasonSleepServiceExit            = 109,
 119     kIOPMSleepReasonDarkWakeThermalEmergency    = 110
 120 };
 121
 122 /*
 123  * Possible C-string sleep reasons found under kRootDomainSleepReasonsKey
 124  */
 125 #define kIOPMClamshellSleepKey                      "Clamshell Sleep"
 126 #define kIOPMPowerButtonSleepKey                    "Power Button Sleep"
 127 #define kIOPMSoftwareSleepKey                       "Software Sleep"
 128 #define kIOPMOSSwitchHibernationKey                 "OS Switch Sleep"
 129 #define kIOPMIdleSleepKey                           "Idle Sleep"
 130 #define kIOPMLowPowerSleepKey                       "Low Power Sleep"
 131 #define kIOPMThermalEmergencySleepKey               "Thermal Emergency Sleep"
 132 #define kIOPMSleepServiceExitKey                    "Sleep Service Back to Sleep"
 133 #define kIOPMDarkWakeThermalEmergencyKey            "Dark Wake Thermal Emergency"
 134
 135 /*! kIOPMPSRestrictedModeKey
 136  *  An IOPMPowerSource property key
 137  *  Its property has an integer value.
 138  *  - value = 1 when the device is in a low power state and not fully functional.
 139  *  - value = 0, or property missing altogether, when the device is
 140  *      not in a restricted mode power state.
 141 */
 142 #define kIOPMPSRestrictedModeKey                    "RestrictedMode"
 143
 144 #pragma mark Stray Bitfields
 145 // Private power commands issued to root domain
 146 // bits 0-7 in IOPM.h
 147
 148 enum {
 149     kIOPMSetValue                   = (1<<16),
 150     // don't sleep on clamshell closure on a portable with AC connected
 151     kIOPMSetDesktopMode             = (1<<17),
 152     // set state of AC adaptor connected
 153     kIOPMSetACAdaptorConnected      = (1<<18)
 154 };
 155
 156 /*****************************************************************************/
 157 /*****************************************************************************/
 158
 159 /*
 160  * PM notification types
 161  */
 162
 163 /*! @constant kIOPMSleepServiceScheduleImmediate
 164  *
 165  * Setting type used in calls to IOPMrootDomain::registerPMSettingController
 166  * Use this type between powerd and IOKit.framework
 167  *
 168  */
 169 #define kIOPMSleepServiceScheduleImmediate     "SleepServiceImmediate"
 170
 171 /*! @constant kIOPMSettingSleepServiceScheduleImmediate
 172  *
 173  * Setting type used in calls to IOPMrootDomain::registerPMSettingController
 174  * Use this type between xnu and AppleRTC
 175  */
 176 #define kIOPMSettingSleepServiceWakeCalendarKey     "SleepServiceWakeCalendarKey"
 177
 178 /*! @constant kIOPMCalendarWakeTypes
 179  *
 180  * These are valid values for IOPM.h:IOPMCalendarStruct->selector
 181  */
 182 enum {
 183     kPMCalendarTypeMaintenance = 1,
 184     kPMCalendarTypeSleepService = 2
 185 };
 186
 187
 188 /* @constant kIOPMStateConsoleShutdown
 189  * @abstract Notification of GUI shutdown state available to kexts.
 190  * @discussion This type can be passed as arguments to registerPMSettingController()
 191  * to receive callbacks.
 192  */
 193 #define kIOPMStateConsoleShutdown   "ConsoleShutdown"
 194
 195 /* @enum ShutdownValues
 196  * @abstract Potential values shared with key kIOPMStateConsoleShutdown
 197  */
 198 enum {
 199 /* @constant kIOPMStateConsoleShutdownNone
 200  * @abstract System shutdown (or restart) hasn't started; system is ON.
 201  * @discussion Next state: 2
 202  */
 203     kIOPMStateConsoleShutdownNone   = 1,
 204 /* @constant kIOPMStateConsoleShutdownPossible
 205  * @abstract User has been presented with the option to shutdown or restart. Shutdown may be cancelled.
 206  * @discussion Next state may be: 1, 4
 207  */
 208     kIOPMStateConsoleShutdownPossible = 2,
 209 /* @constant kIOPMStateConsoleShutdownUnderway
 210  * @abstract Shutdown or restart is proceeding. It may still be cancelled.
 211  * @discussion Next state may be: 1, 4. This state is currently unused.
 212  */
 213     kIOPMStateConsoleShutdownUnderway = 3,
 214 /* @constant kIOPMStateConsoleShutdownCertain
 215  * @abstract Shutdown is in progress and irrevocable.
 216  * @discussion State remains 4 until power is removed from CPU.
 217  */
 218     kIOPMStateConsoleShutdownCertain = 4,
 219 /* @constant kIOPMStateConsoleSULogoutInitiated
 220    Indicates that LoginWindow has initiated a software update restart.
 221    The next logout will not immediately lead to a shutdown.
 222  */
 223     kIOPMStateConsoleSULogoutInitiated = 5
 224 };
 225
 226 /* @constant kIOPMSettingSilentRunningKey
 227  * @abstract Notification of silent running mode changes to kexts.
 228  * @discussion This key can be passed as an argument to registerPMSettingController()
 229  * and also identifies the type of PMSetting notification callback.
 230  */
 231 #define kIOPMSettingSilentRunningKey    "SilentRunning"
 232 #define kIOPMFeatureSilentRunningKey    kIOPMSettingSilentRunningKey
 233
 234 /* @enum SilentRunningFlags
 235  * @abstract The kIOPMSettingSilentRunningKey notification provides an OSNumber
 236  * object with a value described by the following flags.
 237  */
 238 enum {
 239     kIOPMSilentRunningModeOn = 0x00000001
 240 };
 241
 242 /*****************************************************************************/
 243 /*****************************************************************************/
 244
 245 /* PM Statistics - event indices
 246  * These are arguments to IOPMrootDomain::pmStatsRecordEvent().
 247  */
 248 enum {
 249     kIOPMStatsHibernateImageWrite         = 1,
 250     kIOPMStatsHibernateImageRead,
 251     kIOPMStatsDriversNotify,
 252     kIOPMStatsApplicationNotify,
 253     kIOPMStatsLateDriverAcknowledge,
 254     kIOPMStatsLateAppAcknowledge,
 255
 256     // To designate if you're specifying the start or stop end of
 257     // each of the above events, do a bitwise OR of the appropriate
 258     // Start/Stop flag and pass the result to IOPMrootDomain to record
 259     // the event.
 260     kIOPMStatsEventStartFlag              = (1 << 24),
 261     kIOPMStatsEventStopFlag               = (1 << 25)
 262 };
 263
 264 // Keys for IOPMrootDomain registry properties
 265 #define kIOPMSleepStatisticsKey                 "SleepStatistics"
 266 #define kIOPMSleepStatisticsAppsKey             "AppStatistics"
 267 #define kIOPMIdleSleepPreventersKey             "IdleSleepPreventers"
 268 #define kIOPMSystemSleepPreventersKey           "SystemSleepPreventers"
 269
 270 // Application response statistics
 271 #define kIOPMStatsNameKey                       "Name"
 272 #define kIOPMStatsPIDKey                        "Pid"
 273 #define kIOPMStatsTimeMSKey                     "TimeMS"
 274 #define kIOPMStatsApplicationResponseTypeKey    "ResponseType"
 275 #define kIOPMStatsMessageTypeKey                "MessageType"
 276 #define kIOPMStatsPowerCapabilityKey            "PowerCaps"
 277 #define kIOPMStatsSystemTransitionKey           "TransitionType"
 278
 279 // PM Statistics: potential values for the key kIOPMStatsApplicationResponseTypeKey
 280 // entry in the application results array.
 281 #define kIOPMStatsResponseTimedOut      "ResponseTimedOut"
 282 #define kIOPMStatsResponseCancel        "ResponseCancel"
 283 #define kIOPMStatsResponseSlow          "ResponseSlow"
 284 #define kIOPMStatsResponsePrompt        "ResponsePrompt"
 285 #define kIOPMStatsDriverPSChangeSlow    "DriverPSChangeSlow"
 286
 287 struct PMStatsBounds{
 288     uint64_t start;
 289     uint64_t stop;
 290 };
 291 typedef struct {
 292
 293     struct PMStatsBounds    hibWrite;
 294     struct PMStatsBounds    hibRead;
 295 //    bounds    driverNotifySleep;
 296 //    bounds    driverNotifyWake;
 297 //    bounds    appNotifySleep;
 298 //    bounds    appNotifyWake;
 299 //    OSDictionary    *tardyApps;
 300 //    OSDictionary    *tardyDrivers;
 301 } PMStatsStruct;
 302
 303 /*****************************************************************************/
 304
 305 /* PM RootDomain tracePoints
 306  *
 307  * In the sleep/wake process, we expect the sleep trace points to proceed
 308  * in increasing order. Once sleep begins with code kIOPMTracePointSleepStarted,
 309  * we expect sleep to continue in a monotonically increasing order of tracepoints
 310  * to kIOPMTracePointSystemLoginwindowPhase. After trace point SystemLoginWindowPhase,
 311  * the system will return to kIOPMTracePointSystemUp.
 312  *
 313  * If the trace point decreases (instead of increasing) before reaching kIOPMTracePointSystemUp,
 314  * that indicates that the sleep process was cancelled. The cancel reason shall be indicated
 315  * in the cancel tracepoint. (TBD)
 316  */
 317
 318 enum {
 319 /* When kTracePointSystemUp is the latest tracePoint,
 320  * the system is awake. It is not asleep, sleeping, or waking.
 321  *
 322  * Phase begins: At boot, at completion of wake from sleep,
 323  *      immediately following kIOPMTracePointSystemLoginwindowPhase.
 324  * Phase ends: When a sleep attempt is initiated.
 325  */
 326     kIOPMTracePointSystemUp                     = 0,
 327
 328 /* When kIOPMTracePointSleepStarted is the latest tracePoint,
 329  * sleep has been initiated.
 330  *
 331  * Phase begins: At initiation of system sleep (idle or forced).
 332  * Phase ends: PM starts to notify applications of system sleep.
 333  */
 334     kIOPMTracePointSleepStarted                 = 0x10,
 335
 336 /* When kIOPMTracePointSleepApplications is the latest tracePoint,
 337  * a system sleep has been initiated and PM waits for responses
 338  * from notified applications.
 339  *
 340  * Phase begins: Begin to asynchronously fire kIOMessageSystemWillSleep
 341  *      notifications, and also kIOMessageCanSystemSleep for the idle sleep case.
 342  * Phase ends: When PM has received all application responses.
 343  */
 344     kIOPMTracePointSleepApplications            = 0x11,
 345
 346 /* When kIOPMTracePointSleepPriorityClients is the latest tracePoint,
 347  * PM is notifying priority clients and in-kernel system capability
 348  * clients, and waiting for any asynchronous completions.
 349  *
 350  * Phase begins: Synchronous delivery of kIOMessageSystemWillSleep notifications.
 351  * Phase ends: All notified clients have acknowledged.
 352  */
 353     kIOPMTracePointSleepPriorityClients         = 0x12,
 354
 355 /* When kIOPMTracePointSleepWillChangeInterests is the latest tracePoint,
 356  * PM is calling powerStateWillChangeTo() on interested drivers of root domain.
 357  *
 358  * Phase begins: Dispatch a callout thread to call interested drivers.
 359  * Phase ends: Callout thread work done, and acknowledgePowerChange() called
 360  *      by drivers that indicated asynchronous completion.
 361  */
 362     kIOPMTracePointSleepWillChangeInterests     = 0x13,
 363
 364 /* When kIOPMTracePointSleepPowerPlaneDrivers is the latest tracePoint,
 365  * PM is directing power plane drivers to power off in leaf-to-root order.
 366  *
 367  * Phase begins: Root domain informs its power children that it will drop to
 368  *      sleep state. This has a cascade effect and triggers all drivers in
 369  *      the power plane to transition to a lower power state if necessary.
 370  * Phase ends: All power transitions in response to the root domain power
 371  *      change have completed.
 372  */
 373     kIOPMTracePointSleepPowerPlaneDrivers       = 0x14,
 374
 375 /* When kIOPMTracePointSleepDidChangeInterests is the latest tracePoint,
 376  * PM is calling powerStateDidChangeTo() on interested drivers of root domain.
 377  *
 378  * Phase begins: Dispatch a callout thread to call interested drivers.
 379  * Phase ends: Callout thread work done, and acknowledgePowerChange() called
 380  *      by drivers that indicated asynchronous completion.
 381  */
 382     kIOPMTracePointSleepDidChangeInterests      = 0x15,
 383
 384 /* When kIOPMTracePointSleepCapabilityClients is the latest tracePoint,
 385  * PM is notifying system capability clients about system sleep.
 386  *
 387  * Phase begins: Send kIOMessageSystemCapabilityChange notifications to inform
 388  *      capability clients that system has lost all capabilities.
 389  * Phase ends: Finished sending notifications.
 390  */
 391     kIOPMTracePointSleepCapabilityClients       = 0x16,
 392
 393 /* When kIOPMTracePointSleepPlatformActions is the latest tracePoint,
 394  * PM is calling drivers that have registered a platform sleep action.
 395  */
 396     kIOPMTracePointSleepPlatformActions         = 0x17,
 397
 398 /* When kIOPMTracePointSleepCPUs is the latest tracePoint,
 399  * PM is shutting down all non-boot processors.
 400  *
 401  * Phase begins: Shutdown all non-boot processors.
 402  * Phase ends: Reduced to only the boot processor running.
 403  */
 404     kIOPMTracePointSleepCPUs                    = 0x18,
 405
 406 /* When kIOPMTracePointSleepPlatformDriver is the latest tracePoint,
 407  * PM is executing platform dependent code to prepare for system sleep.
 408  */
 409     kIOPMTracePointSleepPlatformDriver          = 0x19,
 410
 411 /* When kIOPMTracePointHibernate is the latest tracePoint,
 412  * PM is writing the hibernate image to disk.
 413  */
 414     kIOPMTracePointHibernate                    = 0x1a,
 415
 416 /* When kIOPMTracePointSystemSleep is the latest tracePoint,
 417  * PM has recorded the final trace point before the hardware platform
 418  * enters sleep state, or low level wakeup is underway - such as restoring
 419  * the hibernate image from disk.
 420  *
 421  * Note: If a system is asleep and then loses power, and it does not have a
 422  * hibernate image to restore from (e.g. hibernatemode = 0), then OS X will
 423  * interpret this power loss as a failure in kIOPMTracePointSystemSleep.
 424  *
 425  * Phase begins: Before the OS directs the hardware to enter sleep state.
 426  * Phase ends: Control returns to the OS on wake, but before recording the first
 427  *      wake trace point.
 428  */
 429     kIOPMTracePointSystemSleep                  = 0x1f,
 430
 431 /* When kIOPMTracePointWakePlatformDriver is the latest tracePoint,
 432  * PM is executing platform dependent code to prepare for system wake.
 433  */
 434     kIOPMTracePointWakePlatformDriver           = 0x21,
 435
 436 /* When kIOPMTracePointWakePlatformActions is the latest tracePoint,
 437  * PM is calling drivers that have registered a platform wake action.
 438  */
 439     kIOPMTracePointWakePlatformActions          = 0x22,
 440
 441 /* When kIOPMTracePointWakeCPUs is the latest tracePoint,
 442  * PM is bringing all non-boot processors online.
 443  */
 444     kIOPMTracePointWakeCPUs                     = 0x23,
 445
 446 /* When kIOPMTracePointWakeWillPowerOnClients is the latest tracePoint,
 447  * PM is sending kIOMessageSystemWillPowerOn to both kernel clients and
 448  * applications. PM also notifies system capability clients about the
 449  * proposed capability change.
 450  *
 451  * Phase begins: Send kIOMessageSystemWillPowerOn and
 452  *      kIOMessageSystemCapabilityChange notifications.
 453  * Phase ends: Finished sending notifications.
 454  */
 455     kIOPMTracePointWakeWillPowerOnClients       = 0x24,
 456
 457 /* When kIOPMTracePointWakeWillChangeInterests is the latest tracePoint,
 458  * PM is calling powerStateWillChangeTo() on interested drivers of root domain.
 459  *
 460  * Phase begins: Dispatch a callout thread to call interested drivers.
 461  * Phase ends: Callout thread work done, and acknowledgePowerChange() called
 462  *      by drivers that indicated asynchronous completion.
 463  */
 464     kIOPMTracePointWakeWillChangeInterests      = 0x25,
 465
 466 /* When kIOPMTracePointWakeDidChangeInterests is the latest tracePoint,
 467  * PM is calling powerStateDidChangeTo() on interested drivers of root domain.
 468  *
 469  * Phase begins: Dispatch a callout thread to call interested drivers.
 470  * Phase ends: Callout thread work done, and acknowledgePowerChange() called
 471  *      by drivers that indicated asynchronous completion.
 472  */
 473     kIOPMTracePointWakeDidChangeInterests       = 0x26,
 474
 475 /* When kIOPMTracePointWakePowerPlaneDrivers is the latest tracePoint,
 476  * PM is directing power plane drivers to power up in root-to-leaf order.
 477  *
 478  * Phase begins: Root domain informs its power children that it transitioned
 479  *      to ON state. This has a cascade effect and triggers all drivers in
 480  *      the power plane to re-evaluate and potentially change power state.
 481  * Phase ends: All power transitions in response to the root domain power
 482  *      change have completed.
 483  */
 484     kIOPMTracePointWakePowerPlaneDrivers        = 0x27,
 485
 486 /* When kIOPMTracePointWakeCapabilityClients is the latest tracePoint,
 487  * PM is notifying system capability clients about system wake, and waiting
 488  * for any asynchronous completions.
 489  *
 490  * Phase begins: Inform capability clients that system has gained capabilities.
 491  * Phase ends: All notified clients have acknowledged.
 492  */
 493     kIOPMTracePointWakeCapabilityClients        = 0x28,
 494
 495 /* When kIOPMTracePointWakeApplications is the latest tracePoint,
 496  * System CPU is powered, PM has powered on each driver.
 497  *
 498  * Phase begins: Send asynchronous kIOMessageSystemHasPoweredOn notifications.
 499  * Phase ends: Finished sending asynchronous notifications.
 500  */
 501     kIOPMTracePointWakeApplications             = 0x29,
 502
 503 /* kIOPMTracePointSystemLoginwindowPhase
 504  * This phase represents a several minute window after the system has powered on.
 505  * Higher levels of system diagnostics are in a heightened state of alert in this phase,
 506  * in case any user errors occurred that we could not detect in software.
 507  *
 508  * Phase begins: After IOPMrootDomain sends kIOMessageSystemHasPoweredOn message.
 509  * Phase ends: When loginwindow calls IOPMSleepWakeSetUUID(NULL) the system shall
 510  *      be considered awake and usable. The next phase shall be kIOPMTracePointSystemUp.
 511  */
 512     kIOPMTracePointSystemLoginwindowPhase       = 0x30,
 513
 514 /* When kIOPMTracePointDarkWakeEntry is the latest tracePoint,
 515  * PM has started a transition from full wake to dark wake.
 516  *
 517  * Phase begins: Start transition to dark wake.
 518  * Phase ends: System in dark wake. Before recording kIOPMTracePointSystemUp.
 519  */
 520     kIOPMTracePointDarkWakeEntry                = 0x31,
 521
 522 /* When kIOPMTracePointDarkWakeExit is the latest tracePoint,
 523  * PM has started a transition from dark wake to full wake.
 524  *
 525  * Phase begins: Start transition to full wake.
 526  * Phase ends: System in full wake. Before recording kIOPMTracePointSystemUp.
 527  */
 528     kIOPMTracePointDarkWakeExit                 = 0x32
 529 };
 530
 531 /*****************************************************************************/
 532
 533 /*
 534 Ê* kIOPMLoginWindowSecurityDebugKey - identifies PM debug data specific to LoginWindow
 535  *  for use with IOPMrootDomain.
 536 Ê*/
 537 #define kIOPMLoginWindowSecurityDebugKey        "LoginWindowSecurity"
 538
 539 // For PM internal use only - key to locate sleep failure results within SCDynamicStore.
 540 #define kIOPMDynamicStoreSleepFailureKey        "SleepFailure"
 541
 542 /*****************************************************************************/
 543
 544 // For IOPMLibPrivate.h
 545 #define kIOPMSleepWakeFailureKey            "PMFailurePhase"
 546 #define kIOPMSleepWakeFailureCodeKey        "PMStatusCode"
 547 #define kIOPMSleepWakeFailureLoginKey       "LWFailurePhase"
 548 #define kIOPMSleepWakeFailureUUIDKey        "UUID"
 549 #define kIOPMSleepWakeFailureDateKey        "Date"
 550 #define kIOPMSleepWakeWdogRebootKey         "SWWdogTriggeredRestart"
 551 #define kIOPMSleepWakeWdogLogsValidKey      "SWWdogLogsValid"
 552
 553 /*****************************************************************************
 554  *
 555  * Root Domain private property keys
 556  *
 557  *****************************************************************************/
 558
 559 /* kIOPMFeatureAutoPowerOffKey
 560  * Feature published if Auto Power Off is supported
 561  */
 562 #define kIOPMFeatureAutoPowerOffKey         "AutoPowerOff"
 563
 564 /* kIOPMAutoPowerOffEnabledKey
 565  * Indicates if Auto Power Off is enabled.
 566  * It has a boolean value.
 567  *  true        == Auto Power Off is enabled
 568  *  false       == Auto Power Off is disabled
 569  *  not present == Auto Power Off is not supported on this hardware
 570  */
 571 #define kIOPMAutoPowerOffEnabledKey         "AutoPowerOff Enabled"
 572
 573 /* kIOPMAutoPowerOffDelayKey
 574  * Key refers to a CFNumberRef that represents the delay in seconds before
 575  * entering the Auto Power Off state.  The property is not present if Auto
 576  * Power Off is unsupported.
 577  */
 578 #define kIOPMAutoPowerOffDelayKey           "AutoPowerOff Delay"
 579
 580 /* kIOPMAutoPowerOffTimerKey
 581  * Key refers to a CFNumberRef that indicates the time in seconds until the
 582  * expiration of the Auto Power Off delay period. This value should be used
 583  * to program a wake alarm before system sleep.
 584  */
 585 #define kIOPMAutoPowerOffTimerKey           "AutoPowerOff Timer"
 586
 587 /* kIOPMUserWakeAlarmScheduledKey
 588  * Key refers to a boolean value that indicates if an user alarm was scheduled
 589  * or pending.
 590  */
 591 #define kIOPMUserWakeAlarmScheduledKey      "UserWakeAlarmScheduled"
 592
 593 /* kIOPMDeepIdleSupportedKey
 594  * Presence of this key indicates Deep Idle is supported on this platform.
 595  * Key will always refer to a value of kOSBooleanTrue.
 596  */
 597 #define kIOPMDeepIdleSupportedKey           "IOPMDeepIdleSupported"
 598
 599 /* kIOPMUserTriggeredFullWakeKey
 600  * Key refers to a boolean value that indicates if the first full wake since
 601  * last system sleep was triggered by the local user. This property is set
 602  * before the initial full wake transition, and removed after powering down
 603  * drivers for system sleep.
 604  */
 605 #define kIOPMUserTriggeredFullWakeKey       "IOPMUserTriggeredFullWake"
 606
 607 /* kIOPMUserIsActiveKey
 608  * Key refers to a boolean value that indicates if the user is active.
 609  */
 610 #define kIOPMUserIsActiveKey                "IOPMUserIsActive"
 611
 612 /* kIOPMDriverWakeEventsKey
 613  * Key refers to a property that should only be examined by powerd.
 614  */
 615 #define kIOPMDriverWakeEventsKey            "IOPMDriverWakeEvents"
 616
 617 /*****************************************************************************
 618  *
 619  * IOPMDriverWakeEvents dictionary keys
 620  *
 621  *****************************************************************************/
 622
 623 #define kIOPMWakeEventTimeKey               "Time"
 624 #define kIOPMWakeEventFlagsKey              "Flags"
 625 #define kIOPMWakeEventReasonKey             "Reason"
 626 #define kIOPMWakeEventDetailsKey            "Details"
 627
 628 /*****************************************************************************
 629  *
 630  * Wake event flags reported to IOPMrootDomain::claimSystemWakeEvent()
 631  *
 632  *****************************************************************************/
 633
 634 #define kIOPMWakeEventSource                0x00000001
 635
 636 /*****************************************************************************
 637  *
 638  * System Sleep Policy
 639  *
 640  *****************************************************************************/
 641
 642 #define kIOPMSystemSleepPolicySignature     0x54504c53
 643 #define kIOPMSystemSleepPolicyVersion       2
 644
 645 /*!
 646  * @defined kIOPMSystemSleepTypeKey
 647  * @abstract Indicates the type of system sleep.
 648  * @discussion An OSNumber property of root domain that describes the type
 649  * of system sleep. This property is set after notifying priority sleep/wake
 650  * clients, but before informing interested drivers and shutting down power
 651  * plane drivers. On a hibernate abort or failure, this property will not be
 652  * updated and will indicate the failed sleep type.
 653  */
 654 #define kIOPMSystemSleepTypeKey             "IOPMSystemSleepType"
 655
 656 struct IOPMSystemSleepPolicyVariables
 657 {
 658     uint32_t    signature;                  // kIOPMSystemSleepPolicySignature
 659     uint32_t    version;                    // kIOPMSystemSleepPolicyVersion
 660
 661     uint64_t    currentCapability;          // current system capability bits
 662     uint64_t    highestCapability;          // highest system capability bits
 663
 664     uint64_t    sleepFactors;               // sleep factor bits
 665     uint32_t    sleepReason;                // kIOPMSleepReason*
 666     uint32_t    sleepPhase;                 // identify the sleep phase
 667     uint32_t    hibernateMode;              // current hibernate mode
 668
 669     uint32_t    standbyDelay;               // standby delay in seconds
 670     uint32_t    poweroffDelay;              // auto-poweroff delay in seconds
 671     uint32_t    scheduledAlarms;            // bitmask of scheduled alarm types
 672     uint32_t    poweroffTimer;              // auto-poweroff timer in seconds
 673
 674     uint32_t    reserved[49];               // pad sizeof 256 bytes
 675 };
 676
 677 enum {
 678     kIOPMAlarmBitDebugWake                  = 0x01,
 679     kIOPMAlarmBitCalendarWake               = 0x02,
 680     kIOPMAlarmBitMaintenanceWake            = 0x04,
 681     kIOPMAlarmBitSleepServiceWake           = 0x08
 682 };
 683
 684 enum {
 685     kIOPMSleepPhase0 = 0,
 686     kIOPMSleepPhase1,
 687     kIOPMSleepPhase2
 688 };
 689
 690 // Sleep Factor Mask / Bits
 691 enum {
 692     kIOPMSleepFactorSleepTimerWake          = 0x00000001ULL,
 693     kIOPMSleepFactorLidOpen                 = 0x00000002ULL,
 694     kIOPMSleepFactorACPower                 = 0x00000004ULL,
 695     kIOPMSleepFactorBatteryLow              = 0x00000008ULL,
 696     kIOPMSleepFactorStandbyNoDelay          = 0x00000010ULL,
 697     kIOPMSleepFactorStandbyForced           = 0x00000020ULL,
 698     kIOPMSleepFactorStandbyDisabled         = 0x00000040ULL,
 699     kIOPMSleepFactorUSBExternalDevice       = 0x00000080ULL,
 700     kIOPMSleepFactorBluetoothHIDDevice      = 0x00000100ULL,
 701     kIOPMSleepFactorExternalMediaMounted    = 0x00000200ULL,
 702     kIOPMSleepFactorThunderboltDevice       = 0x00000400ULL,
 703     kIOPMSleepFactorRTCAlarmScheduled       = 0x00000800ULL,
 704     kIOPMSleepFactorMagicPacketWakeEnabled  = 0x00001000ULL,
 705     kIOPMSleepFactorHibernateForced         = 0x00010000ULL,
 706     kIOPMSleepFactorAutoPowerOffDisabled    = 0x00020000ULL,
 707     kIOPMSleepFactorAutoPowerOffForced      = 0x00040000ULL,
 708     kIOPMSleepFactorExternalDisplay         = 0x00080000ULL,
 709     kIOPMSleepFactorNetworkKeepAliveActive  = 0x00100000ULL,
 710     kIOPMSleepFactorLocalUserActivity       = 0x00200000ULL,
 711     kIOPMSleepFactorHibernateFailed         = 0x00400000ULL,
 712     kIOPMSleepFactorThermalWarning          = 0x00800000ULL,
 713     kIOPMSleepFactorDisplayCaptured         = 0x01000000ULL
 714 };
 715
 716 // System Sleep Types
 717 enum {
 718     kIOPMSleepTypeInvalid                   = 0,
 719     kIOPMSleepTypeAbortedSleep              = 1,
 720     kIOPMSleepTypeNormalSleep               = 2,
 721     kIOPMSleepTypeSafeSleep                 = 3,
 722     kIOPMSleepTypeHibernate                 = 4,
 723     kIOPMSleepTypeStandby                   = 5,
 724     kIOPMSleepTypePowerOff                  = 6,
 725     kIOPMSleepTypeDeepIdle                  = 7,
 726     kIOPMSleepTypeLast                      = 8
 727 };
 728
 729 // System Sleep Flags
 730 enum {
 731     kIOPMSleepFlagDisableHibernateAbort     = 0x00000001,
 732     kIOPMSleepFlagDisableUSBWakeEvents      = 0x00000002,
 733     kIOPMSleepFlagDisableBatlowAssertion    = 0x00000004,
 734     kIOPMSleepFlagDisableS4WakeSources      = 0x00000008
 735 };
 736
 737 // System Wake Events
 738 enum {
 739     kIOPMWakeEventLidOpen                   = 0x00000001,
 740     kIOPMWakeEventLidClose                  = 0x00000002,
 741     kIOPMWakeEventACAttach                  = 0x00000004,
 742     kIOPMWakeEventACDetach                  = 0x00000008,
 743     kIOPMWakeEventCDInsert                  = 0x00000010,
 744     kIOPMWakeEventCDEject                   = 0x00000020,
 745     kIOPMWakeEventHPDAttach                 = 0x00000040,
 746     kIOPMWakeEventHPDDetach                 = 0x00000080,
 747     kIOPMWakeEventPowerButton               = 0x00000100,
 748     kIOPMWakeEventG3PowerOn                 = 0x00000200,
 749     kIOPMWakeEventUserPME                   = 0x00000400,
 750     kIOPMWakeEventSleepTimer                = 0x00000800,
 751     kIOPMWakeEventBatteryLow                = 0x00001000,
 752     kIOPMWakeEventDarkPME                   = 0x00002000
 753 };
 754
 755 /*!
 756  * @defined kIOPMSystemSleepParametersKey
 757  * @abstract Sleep parameters describing the upcoming sleep
 758  * @discussion Root domain updates this OSData property before system sleep
 759  * to pass sleep parameters to the platform driver.  Some of the parameters
 760  * are based on the chosen entry in the system sleep policy table.
 761  */
 762 #define kIOPMSystemSleepParametersKey       "IOPMSystemSleepParameters"
 763 #define kIOPMSystemSleepParametersVersion   2
 764
 765 struct IOPMSystemSleepParameters
 766 {
 767     uint16_t    version;
 768     uint16_t    reserved1;
 769     uint32_t    sleepType;
 770     uint32_t    sleepFlags;
 771     uint32_t    ecWakeEvents;
 772     uint32_t    ecWakeTimer;
 773     uint32_t    ecPoweroffTimer;
 774     uint32_t    reserved2[10];
 775 } __attribute__((packed));
 776
 777
 778 /*
 779  * Sleep Wake debug buffer header
 780  */
 781 typedef struct {
 782    uint32_t signature;
 783    uint32_t alloc_size;
 784    uint32_t          crc;             /* CRC for spindump & following data.*/
 785    uint32_t          spindump_offset; /* Offset at which spindump offset is stored */
 786    uint32_t          spindump_size;
 787    uint8_t           is_osx_watchdog;
 788
 789    /* All members from UUID onwards are saved into log file */
 790    char             UUID[44];
 791    char             cps[9];          /* Current power state */
 792    char             PMStatusCode[32];
 793    char             reason[32];
 794 } swd_hdr;
 795
 796 /*
 797  * Structure between stackshot samples, expected by spindump
 798  */
 799 typedef struct {
 800     uint32_t magic;      // 0xbad51ee4
 801     uint32_t size;       // Size of the stackshot buffer following this struct
 802 } swd_stackshot_hdr;
 803
 804
 805 #define SWD_HDR_SIGNATURE       0xdeb8da2a
 806 #define SWD_STACKSHOTHDR_MAGIC  0xbad51ee4  // expected by spindump
 807
 808 #define SWD_BUF_SIZE            (40*PAGE_SIZE)
 809 #define SWD_INITIAL_STACK_SIZE  ((SWD_BUF_SIZE/2)-sizeof(swd_hdr))
 810
 811 #define SWD_SPINDUMP_SIZE          (256*1024)
 812 #define SWD_INITIAL_SPINDUMP_SIZE  ((SWD_SPINDUMP_SIZE/2)-sizeof(swd_hdr))
 813
 814 /* Bits in swd_flags */
 815 #define SWD_WDOG_ENABLED        0x01
 816 #define SWD_BOOT_BY_SW_WDOG     0x02
 817 #define SWD_BOOT_BY_OSX_WDOG    0x04
 818 #define SWD_VALID_LOGS          0x08
 819 #define SWD_LOGS_IN_FILE        0x10
 820 #define SWD_LOGS_IN_MEM         0x20
 821
 822 /* Filenames associated with the stackshots/logs generated by the SWD */
 823 #define kSleepWakeStackBinFilename          "/var/log/SleepWakeStacks.bin"
 824 #define kSleepWakeStackFilename             "/var/log/SleepWakeStacks.dump"
 825 #define kSleepWakeLogFilename               "/var/log/SleepWakeLog.dump"
 826 #define kAppleOSXWatchdogStackFilename      "/var/log/AppleOSXWatchdogStacks.dump"
 827 #define kAppleOSXWatchdogLogFilename        "/var/log/AppleOSXWatchdogLog.dump"
 828
 829 inline char const* getDumpStackFilename(swd_hdr *hdr)
 830 {
 831     if (hdr && hdr->is_osx_watchdog)
 832         return kAppleOSXWatchdogStackFilename;
 833     return kSleepWakeStackFilename;
 834 }
 835
 836 inline char const* getDumpLogFilename(swd_hdr *hdr)
 837 {
 838     if (hdr && hdr->is_osx_watchdog)
 839         return kAppleOSXWatchdogLogFilename;
 840     return kSleepWakeLogFilename;
 841 }
 842
 843 /* RootDomain IOReporting channels */
 844 #define kSleepCntChID IOREPORT_MAKEID('S','l','e','e','p','C','n','t')
 845 #define kDarkWkCntChID IOREPORT_MAKEID('G','U','I','W','k','C','n','t')
 846 #define kUserWkCntChID IOREPORT_MAKEID('D','r','k','W','k','C','n','t')
 847
 848 /*
 849  * kAssertDelayChID - Histogram of time elapsed before assertion after wake.
 850  */
 851 #define kAssertDelayBcktCnt     11
 852 #define kAssertDelayBcktSize    3
 853 #define kAssertDelayChID IOREPORT_MAKEID('r','d','A','s','r','t','D','l')
 854
 855 /*
 856  * kSleepDelaysChID - Histogram of time taken to put system to sleep
 857  */
 858 #define kSleepDelaysBcktCnt     13
 859 #define kSleepDelaysBcktSize    10
 860 #define kSleepDelaysChID IOREPORT_MAKEID('r','d','S','l','p','D','l','y')
 861
 862 /* Sleep Options/settings */
 863 #define kSleepOptionDisplayCapturedModeKey         "DisplayCapturedMode"
 864
 865
 866 #if defined(KERNEL) && defined(__cplusplus)
 867
 868 /*!
 869  * @defined kIOPMInstallSystemSleepPolicyHandlerKey
 870  * @abstract Name of the platform function to install a sleep policy handler.
 871  * @discussion Pass to IOPMrootDomain::callPlatformFunction(), with a pointer
 872  * to the C-function handler at param1, and an optional target at param2, to
 873  * register a sleep policy handler. Only a single sleep policy handler can
 874  * be installed.
 875  */
 876 #define kIOPMInstallSystemSleepPolicyHandlerKey \
 877         "IOPMInstallSystemSleepPolicyHandler"
 878
 879 typedef IOReturn (*IOPMSystemSleepPolicyHandler)(
 880         void * target,
 881         const IOPMSystemSleepPolicyVariables * vars,
 882         IOPMSystemSleepParameters * params );
 883
 884 #endif /* KERNEL */
 885
 886 /*****************************************************************************
 887  *
 888  * Performance Warning
 889  *
 890  *****************************************************************************/
 891
 892 /* Performance Warning Key
 893  * Key for performance warning event published using IOPMrootDomain::
 894  * systemPowerEventOccurred()
 895  */
 896 #define kIOPMPerformanceWarningKey          "Performance_Warning"
 897
 898 /* Performance warning values */
 899 enum {
 900   kIOPMPerformanceNormal    = 0,
 901   kIOPMPerformanceWarning   = 100
 902 };
 903
 904 #endif /* ! _IOKIT_IOPMPRIVATE_H */