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