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