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