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