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