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