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