1 /* 2 * Copyright (c) 1998-2005 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_IOPM_H 29 #define _IOKIT_IOPM_H 30 31 #include <IOKit/IOTypes.h> 32 #include <IOKit/IOMessage.h> 33 #include <IOKit/IOReturn.h> 34 35 /*! @header IOPM.h 36 * @abstract Defines power management constants and keys used by both in-kernel and user space power management. 37 * @discussion IOPM.h defines a range of power management constants used in several in-kernel and user space APIs. Most significantly, the IOPMPowerFlags used to specify the fields of an IOPMPowerState struct are defined here. 38 * 39 * Most of the constants defined in IOPM.h are deprecated or for Apple internal use only, and are not elaborated on in headerdoc. 40 */ 41 42 enum { 43 kIOPMMaxPowerStates = 10, 44 IOPMMaxPowerStates = kIOPMMaxPowerStates 45 }; 46 47 /*! @enum IOPMPowerFlags 48 * @abstract Bits are used in defining capabilityFlags, inputPowerRequirements, and outputPowerCharacter in the IOPMPowerState structure. 49 * @discussion These bits may be bitwise-OR'd together in the IOPMPowerState capabilityFlags field, the outputPowerCharacter field, and/or the inputPowerRequirement field. 50 * 51 * The comments clearly mark whether each flag should be used in the capabilityFlags field, outputPowerCharacter field, and inputPowerRequirement field, or all three. 52 * 53 * The value of capabilityFlags, inputPowerRequirement or outputPowerCharacter may be 0. Most drivers implement their 'OFF' state, used when asleep, by defininf each of the 3 fields as 0. 54 * 55 * The bits listed below are only the most common bits used to define a device's power states. Your device's IO family may require that your device specify other input or output power flags to interact properly. Consult family-specific documentation to determine if your IOPower plane parents or children require other power flags; they probably don't. 56 * 57 * @constant kIOPMPowerOn Indicates the device is on, requires power, and provides power. Useful as a: Capability, InputPowerRequirement, OutputPowerCharacter 58 * 59 * @constant kIOPMDeviceUsable Indicates the device is usable in this state. Useful only as a Capability 60 * 61 * @constant kIOPMLowPower 62 * Indicates device is in a low power state. May be bitwis-OR'd together 63 * with kIOPMDeviceUsable flag, to indicate the device is still usable. 64 * 65 * A device with a capability of kIOPMLowPower may: 66 * Require either 0 or kIOPMPowerOn from its power parent 67 * Offer either kIOPMLowPower, kIOPMPowerOn, or 0 (no power at all) 68 * to its power plane children. 69 * 70 * Useful only as a Capability, although USB drivers should consult USB family documentation for other valid circumstances to use the kIOPMLowPower bit. 71 * 72 * @constant kIOPMPreventIdleSleep 73 * In the capability field of a power state, disallows idle system sleep while the device is in that state. 74 * 75 * For example, displays and disks set this capability for their ON power state; since the system may not idle sleep while the display (and thus keyboard or mouse) or the disk is active. 76 * 77 * Useful only as a Capability. 78 * 79 * @constant kIOPMSleepCapability 80 * Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities. 81 * 82 * @constant kIOPMRestartCapability 83 * Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities. 84 * 85 * @constant kIOPMSleep 86 * Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities. 87 * 88 * @constant kIOPMRestart 89 * Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities. 90 * 91 * @constant kIOPMInitialDeviceState 92 * Indicates the initial power state for the device. If <code>initialPowerStateForDomainState()</code> returns a power state with this flag set in the capability field, then the initial power change is performed without calling the driver's <code>setPowerState()</code>. 93 * 94 * @constant kIOPMRootDomainState 95 * An indication that the power flags represent the state of the root power 96 * domain. This bit must not be set in the IOPMPowerState structure. 97 * Power Management may pass this bit to initialPowerStateForDomainState() 98 * to map from a global system state to the desired device state. 99 */ 100 typedef unsigned long IOPMPowerFlags; 101 enum { 102 kIOPMPowerOn = 0x00000002, 103 kIOPMDeviceUsable = 0x00008000, 104 kIOPMLowPower = 0x00010000, 105 #if PRIVATE 106 kIOPMAOTPower = 0x00020000, 107 kIOPMAOTCapability = kIOPMAOTPower, 108 #endif /* PRIVATE */ 109 kIOPMPreventIdleSleep = 0x00000040, 110 kIOPMSleepCapability = 0x00000004, 111 kIOPMRestartCapability = 0x00000080, 112 kIOPMSleep = 0x00000001, 113 kIOPMRestart = 0x00000080, 114 kIOPMInitialDeviceState = 0x00000100, 115 kIOPMRootDomainState = 0x00000200 116 }; 117 118 /* 119 * Private IOPMPowerFlags 120 * 121 * For Apple use only 122 * Not for use with non-Apple drivers 123 * Their behavior is undefined 124 */ 125 enum { 126 kIOPMClockNormal = 0x0004, 127 kIOPMClockRunning = 0x0008, 128 kIOPMPreventSystemSleep = 0x0010, 129 kIOPMDoze = 0x0400, 130 kIOPMChildClamp = 0x0080, 131 kIOPMChildClamp2 = 0x0200, 132 kIOPMNotPowerManaged = 0x0800 133 }; 134 135 /* 136 * Deprecated IOPMPowerFlags 137 * Their behavior is undefined when used in IOPMPowerState 138 * Capability, InputPowerRequirement, or OutputPowerCharacter fields. 139 */ 140 enum { 141 kIOPMMaxPerformance = 0x4000, 142 kIOPMPassThrough = 0x0100, 143 kIOPMAuxPowerOn = 0x0020, 144 kIOPMNotAttainable = 0x0001, 145 kIOPMContextRetained = 0x2000, 146 kIOPMConfigRetained = 0x1000, 147 kIOPMStaticPowerValid = 0x0800, 148 kIOPMSoftSleep = 0x0400, 149 kIOPMCapabilitiesMask = kIOPMPowerOn | kIOPMDeviceUsable | 150 kIOPMMaxPerformance | kIOPMContextRetained | 151 kIOPMConfigRetained | kIOPMSleepCapability | 152 kIOPMRestartCapability 153 }; 154 155 /* 156 * Support for old names of IOPMPowerFlag constants 157 */ 158 enum { 159 IOPMNotAttainable = kIOPMNotAttainable, 160 IOPMPowerOn = kIOPMPowerOn, 161 IOPMClockNormal = kIOPMClockNormal, 162 IOPMClockRunning = kIOPMClockRunning, 163 IOPMAuxPowerOn = kIOPMAuxPowerOn, 164 IOPMDeviceUsable = kIOPMDeviceUsable, 165 IOPMMaxPerformance = kIOPMMaxPerformance, 166 IOPMContextRetained = kIOPMContextRetained, 167 IOPMConfigRetained = kIOPMConfigRetained, 168 IOPMNotPowerManaged = kIOPMNotPowerManaged, 169 IOPMSoftSleep = kIOPMSoftSleep 170 }; 171 172 173 enum { 174 kIOPMNextHigherState = 1, 175 kIOPMHighestState = 2, 176 kIOPMNextLowerState = 3, 177 kIOPMLowestState = 4 178 }; 179 180 enum { 181 IOPMNextHigherState = kIOPMNextHigherState, 182 IOPMHighestState = kIOPMHighestState, 183 IOPMNextLowerState = kIOPMNextLowerState, 184 IOPMLowestState = kIOPMLowestState 185 }; 186 187 // Internal commands used by power managment command queue 188 enum { 189 kIOPMBroadcastAggressiveness = 1, 190 kIOPMUnidleDevice 191 }; 192 193 // Power consumption unknown value 194 enum { 195 kIOPMUnknown = 0xFFFF 196 }; 197 198 /******************************************************************************* 199 * 200 * Root Domain property keys of interest 201 * 202 ******************************************************************************/ 203 204 /* AppleClamshellState 205 * reflects the state of the clamshell (lid) on a portable. 206 * It has a boolean value. 207 * true == clamshell is closed 208 * false == clamshell is open 209 * not present == no clamshell on this hardware 210 */ 211 #define kAppleClamshellStateKey "AppleClamshellState" 212 213 /* AppleClamshellCausesSleep 214 * reflects the clamshell close behavior on a portable. 215 * It has a boolean value. 216 * true == system will sleep when clamshell is closed 217 * false == system will not sleep on clamshell close 218 * (typically external display mode) 219 * not present == no clamshell on this hardware 220 */ 221 #define kAppleClamshellCausesSleepKey "AppleClamshellCausesSleep" 222 223 /* kIOPMSleepWakeUUIDKey 224 * Key refers to a CFStringRef that will uniquely identify 225 * a sleep/wake cycle for logging & tracking. 226 * The key becomes valid at the beginning of a sleep cycle - before we 227 * initiate any sleep/wake notifications. 228 * The key becomes invalid at the completion of a system wakeup. The 229 * property will not be present in the IOPMrootDomain's registry entry 230 * when it is invalid. 231 * 232 * See IOPMrootDomain notification kIOPMMessageSleepWakeUUIDChange 233 */ 234 #define kIOPMSleepWakeUUIDKey "SleepWakeUUID" 235 236 /* kIOPMBootSessionUUIDKey 237 * Key refers to a CFStringRef that will uniquely identify 238 * a boot cycle. 239 * The key becomes valid at boot time and remains valid 240 * till shutdown. The property value will remain same across 241 * sleep/wake/hibernate cycle. 242 */ 243 #define kIOPMBootSessionUUIDKey "BootSessionUUID" 244 245 /* kIOPMDeepSleepEnabledKey 246 * Indicates the Deep Sleep enable state. 247 * It has a boolean value. 248 * true == Deep Sleep is enabled 249 * false == Deep Sleep is disabled 250 * not present == Deep Sleep is not supported on this hardware 251 */ 252 #define kIOPMDeepSleepEnabledKey "Standby Enabled" 253 254 /* kIOPMDeepSleepDelayKey 255 * Key refers to a CFNumberRef that represents the delay in seconds before 256 * entering Deep Sleep state when on battery power and when remaining 257 * battery capacity is below a particular threshold (e.g., 50%.) The 258 * property is not present if Deep Sleep is unsupported. 259 */ 260 #define kIOPMDeepSleepDelayKey "Standby Delay" 261 262 /* kIOPMDeepSleepDelayHighKey 263 * Key refers to a CFNumberRef that represents the delay in seconds before 264 * entering Deep Sleep state. This is used instead of the value specified by 265 * kIOPMDeepSleepDelayKey if the remaining battery capacity is above a 266 * particular threshold (e.g. 50%) or on AC power. The property is not 267 * present if Deep Sleep is unsupported. 268 */ 269 #define kIOPMDeepSleepDelayHighKey "High Standby Delay" 270 271 /* kIOPMLowBatteryThresholdKey 272 * Key refers to a CFNumberRef that represents the threshold used to choose 273 * between the normal deep sleep delay and the high deep sleep delay (as a 274 * percentage of total battery capacity remaining.) The property is not 275 * present if Deep Sleep is unsupported. 276 */ 277 #define kIOPMStandbyBatteryThresholdKey "Standby Battery Threshold" 278 279 /* kIOPMDestroyFVKeyOnStandbyKey 280 * Specifies if FileVault key can be stored when going to standby mode 281 * It has a boolean value, 282 * true == Destroy FV key when going to standby mode 283 * false == Retain FV key when going to standby mode 284 * not present == Retain FV key when going to standby mode 285 */ 286 #define kIOPMDestroyFVKeyOnStandbyKey "DestroyFVKeyOnStandby" 287 288 /******************************************************************************* 289 * 290 * Properties that can control power management behavior 291 * 292 ******************************************************************************/ 293 294 /* kIOPMResetPowerStateOnWakeKey 295 * If an IOService publishes this key with the value of kOSBooleanTrue, 296 * then PM will disregard the influence from changePowerStateToPriv() or 297 * any activity tickles that occurred before system sleep when resolving 298 * the initial device power state on wake. Influences from power children 299 * and changePowerStateTo() are not eliminated. At the earliest opportunity 300 * upon system wake, PM will query the driver for a new power state to be 301 * installed as the initial changePowerStateToPriv() influence, by calling 302 * initialPowerStateForDomainState() with both kIOPMRootDomainState and 303 * kIOPMPowerOn flags set. The default implementation will always return 304 * the lowest power state. Drivers can override this default behavior to 305 * immediately raise the power state when there are work blocked on the 306 * power change, and cannot afford to wait until the next activity tickle. 307 * This property should be statically added to a driver's plist or set at 308 * runtime before calling PMinit(). 309 */ 310 #define kIOPMResetPowerStateOnWakeKey "IOPMResetPowerStateOnWake" 311 312 /******************************************************************************* 313 * 314 * Driver PM Assertions 315 * 316 ******************************************************************************/ 317 318 /* Driver Assertion bitfield description 319 * Driver PM assertions are defined by these bits. 320 */ 321 enum { 322 /*! kIOPMDriverAssertionCPUBit 323 * When set, PM kernel will prefer to leave the CPU and core hardware 324 * running in "Dark Wake" state, instead of sleeping. 325 */ 326 kIOPMDriverAssertionCPUBit = 0x01, 327 328 /*! kIOPMDriverAssertionPreventSystemIdleSleepBit 329 * When set, the system should not idle sleep. This does not prevent 330 * demand sleep. 331 */ 332 kIOPMDriverAssertionPreventSystemIdleSleepBit = 0x02, 333 334 /*! kIOPMDriverAssertionUSBExternalDeviceBit 335 * When set, driver is informing PM that an external USB device is attached. 336 */ 337 kIOPMDriverAssertionUSBExternalDeviceBit = 0x04, 338 339 /*! kIOPMDriverAssertionBluetoothHIDDevicePairedBit 340 * When set, driver is informing PM that a Bluetooth HID device is paired. 341 */ 342 kIOPMDriverAssertionBluetoothHIDDevicePairedBit = 0x08, 343 344 /*! kIOPMDriverAssertionExternalMediaMountedBit 345 * When set, driver is informing PM that an external media is mounted. 346 */ 347 kIOPMDriverAssertionExternalMediaMountedBit = 0x10, 348 349 /*! kIOPMDriverAssertionReservedBit5 350 * Reserved for Thunderbolt. 351 */ 352 kIOPMDriverAssertionReservedBit5 = 0x20, 353 354 /*! kIOPMDriverAssertionPreventDisplaySleepBit 355 * When set, the display should remain powered on while the system's awake. 356 */ 357 kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, 358 359 /*! kIOPMDriverAssertionReservedBit7 360 * Reserved for storage family. 361 */ 362 kIOPMDriverAssertionReservedBit7 = 0x80, 363 364 /*! kIOPMDriverAssertionMagicPacketWakeEnabledBit 365 * When set, driver is informing PM that magic packet wake is enabled. 366 */ 367 kIOPMDriverAssertionMagicPacketWakeEnabledBit = 0x100, 368 369 /*! kIOPMDriverAssertionNetworkKeepAliveActiveBit 370 * When set, driver is informing PM that it is holding the network 371 * interface up to do TCPKeepAlive 372 */ 373 kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200, 374 375 /*! kIOPMDriverAssertionForceWakeupBit 376 * When set, the system will immediately wake up the CPU after going to sleep. 377 */ 378 kIOPMDriverAssertionForceWakeupBit = 0x400, 379 380 /*! kIOPMDriverAssertionForceFullWakeupBit 381 * When set, the system will immediately do a full wakeup after going to sleep. 382 */ 383 kIOPMDriverAssertionForceFullWakeupBit = 0x800, 384 }; 385 386 /* kIOPMAssertionsDriverKey 387 * This kIOPMrootDomain key refers to a CFNumberRef property, containing 388 * a bitfield describing the aggregate PM assertion levels. 389 * Example: A value of 0 indicates that no driver has asserted anything. 390 * Or, a value of <link>kIOPMDriverAssertionCPUBit</link> 391 * indicates that a driver (or drivers) have asserted a need for CPU and video. 392 */ 393 #define kIOPMAssertionsDriverKey "DriverPMAssertions" 394 395 /* kIOPMAssertionsDriverKey 396 * This kIOPMrootDomain key refers to a CFNumberRef property, containing 397 * a bitfield describing the aggregate PM assertion levels. 398 * Example: A value of 0 indicates that no driver has asserted anything. 399 * Or, a value of <link>kIOPMDriverAssertionCPUBit</link> 400 * indicates that a driver (or drivers) have asserted a need for CPU and video. 401 */ 402 #define kIOPMAssertionsDriverDetailedKey "DriverPMAssertionsDetailed" 403 404 /******************************************************************************* 405 * 406 * Kernel Driver assertion detailed dictionary keys 407 * 408 * Keys decode the Array & dictionary data structure under IOPMrootDomain property 409 * kIOPMAssertionsDriverKey. 410 * 411 */ 412 #define kIOPMDriverAssertionIDKey "ID" 413 #define kIOPMDriverAssertionCreatedTimeKey "CreatedTime" 414 #define kIOPMDriverAssertionModifiedTimeKey "ModifiedTime" 415 #define kIOPMDriverAssertionOwnerStringKey "Owner" 416 #define kIOPMDriverAssertionOwnerServiceKey "ServicePtr" 417 #define kIOPMDriverAssertionRegistryEntryIDKey "RegistryEntryID" 418 #define kIOPMDriverAssertionLevelKey "Level" 419 #define kIOPMDriverAssertionAssertedKey "Assertions" 420 421 /******************************************************************************* 422 * 423 * Root Domain general interest messages 424 * 425 * Available by registering for interest type 'gIOGeneralInterest' 426 * on IOPMrootDomain. 427 * 428 ******************************************************************************/ 429 430 /* kIOPMMessageClamshellStateChange 431 * Delivered as a general interest notification on the IOPMrootDomain 432 * IOPMrootDomain sends this message when state of either AppleClamshellState 433 * or AppleClamshellCausesSleep changes. If this clamshell change results in 434 * a sleep, the sleep will initiate soon AFTER delivery of this message. 435 * The state of both variables is encoded in a bitfield argument sent with 436 * the message. Check bits 0 and 1 using kClamshellStateBit & kClamshellSleepBit 437 */ 438 enum { 439 kClamshellStateBit = (1 << 0), 440 kClamshellSleepBit = (1 << 1) 441 }; 442 443 #define kIOPMMessageClamshellStateChange \ 444 iokit_family_msg(sub_iokit_powermanagement, 0x100) 445 446 /* kIOPMMessageFeatureChange 447 * Delivered when the set of supported features ("Supported Features" dictionary 448 * under IOPMrootDomain registry) changes in some way. Typically addition or 449 * removal of a supported feature. 450 * RootDomain passes no argument with this message. 451 */ 452 #define kIOPMMessageFeatureChange \ 453 iokit_family_msg(sub_iokit_powermanagement, 0x110) 454 455 /* kIOPMMessageInflowDisableCancelled 456 * The battery has drained completely to its "Fully Discharged" state. 457 * If a user process has disabled battery inflow for battery 458 * calibration, we forcibly re-enable Inflow at this point. 459 * If inflow HAS been forcibly re-enabled, bit 0 460 * (kInflowForciblyEnabledBit) will be set. 461 */ 462 enum { 463 kInflowForciblyEnabledBit = (1 << 0) 464 }; 465 466 /* kIOPMMessageInternalBatteryFullyDischarged 467 * The battery has drained completely to its "Fully Discharged" state. 468 */ 469 #define kIOPMMessageInternalBatteryFullyDischarged \ 470 iokit_family_msg(sub_iokit_powermanagement, 0x120) 471 472 /* kIOPMMessageSystemPowerEventOccurred 473 * Some major system thermal property has changed, and interested clients may 474 * modify their behavior. 475 */ 476 #define kIOPMMessageSystemPowerEventOccurred \ 477 iokit_family_msg(sub_iokit_powermanagement, 0x130) 478 479 /* kIOPMMessageSleepWakeUUIDChange 480 * Either a new SleepWakeUUID has been specified at the beginning of a sleep, 481 * or we're removing the existing property upon completion of a wakeup. 482 */ 483 #define kIOPMMessageSleepWakeUUIDChange \ 484 iokit_family_msg(sub_iokit_powermanagement, 0x140) 485 486 /* kIOPMMessageSleepWakeUUIDSet 487 * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when 488 * a new UUID has been specified. 489 */ 490 #define kIOPMMessageSleepWakeUUIDSet ((void *)1) 491 492 /* kIOPMMessageSleepWakeUUIDCleared 493 * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when 494 * the current UUID has been removed. 495 */ 496 #define kIOPMMessageSleepWakeUUIDCleared ((void *)NULL) 497 498 /*! kIOPMMessageDriverAssertionsChanged 499 * Sent when kernel PM driver assertions have changed. 500 */ 501 #define kIOPMMessageDriverAssertionsChanged \ 502 iokit_family_msg(sub_iokit_powermanagement, 0x150) 503 504 /*! kIOPMMessageDarkWakeThermalEmergency 505 * Sent when machine becomes unsustainably warm in DarkWake. 506 * Kernel PM might choose to put the machine back to sleep right after. 507 */ 508 #define kIOPMMessageDarkWakeThermalEmergency \ 509 iokit_family_msg(sub_iokit_powermanagement, 0x160) 510 511 /******************************************************************************* 512 * 513 * Power commands issued to root domain 514 * Use with IOPMrootDomain::receivePowerNotification() 515 * 516 * These commands are issued from system drivers only: 517 * ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily 518 * 519 * TODO: deprecate kIOPMAllowSleep and kIOPMPreventSleep 520 ******************************************************************************/ 521 enum { 522 kIOPMSleepNow = (1 << 0),// put machine to sleep now 523 kIOPMAllowSleep = (1 << 1),// allow idle sleep 524 kIOPMPreventSleep = (1 << 2),// do not allow idle sleep 525 kIOPMPowerButton = (1 << 3),// power button was pressed 526 kIOPMClamshellClosed = (1 << 4),// clamshell was closed 527 kIOPMPowerEmergency = (1 << 5),// battery dangerously low 528 kIOPMDisableClamshell = (1 << 6),// do not sleep on clamshell closure 529 kIOPMEnableClamshell = (1 << 7),// sleep on clamshell closure 530 kIOPMProcessorSpeedChange = (1 << 8),// change the processor speed 531 kIOPMOverTemp = (1 << 9),// system dangerously hot 532 kIOPMClamshellOpened = (1 << 10),// clamshell was opened 533 kIOPMDWOverTemp = (1 << 11),// DarkWake thermal limits exceeded. 534 kIOPMPowerButtonUp = (1 << 12),// Power button up 535 kIOPMProModeEngaged = (1 << 13),// Fans entered 'ProMode' 536 kIOPMProModeDisengaged = (1 << 14) // Fans exited 'ProMode' 537 }; 538 539 540 /******************************************************************************* 541 * 542 * Power Management Return Codes 543 * 544 ******************************************************************************/ 545 enum { 546 kIOPMNoErr = 0, 547 548 // Returned by driver's setPowerState(), powerStateWillChangeTo(), 549 // powerStateDidChangeTo(), or acknowledgeSetPowerState() to 550 // implicitly acknowledge power change upon function return. 551 kIOPMAckImplied = 0, 552 553 // Deprecated 554 kIOPMWillAckLater = 1, 555 556 // Returned by requestPowerDomainState() to indicate 557 // unrecognized specification parameter. 558 kIOPMBadSpecification = 4, 559 560 // Returned by requestPowerDomainState() to indicate 561 // no power state matches search specification. 562 kIOPMNoSuchState = 5, 563 564 // Deprecated 565 kIOPMCannotRaisePower = 6, 566 567 // Deprecated 568 kIOPMParameterError = 7, 569 570 // Returned when power management state is accessed 571 // before driver has called PMinit(). 572 kIOPMNotYetInitialized = 8, 573 574 // And the old constants; deprecated 575 IOPMNoErr = kIOPMNoErr, 576 IOPMAckImplied = kIOPMAckImplied, 577 IOPMWillAckLater = kIOPMWillAckLater, 578 IOPMBadSpecification = kIOPMBadSpecification, 579 IOPMNoSuchState = kIOPMNoSuchState, 580 IOPMCannotRaisePower = kIOPMCannotRaisePower, 581 IOPMParameterError = kIOPMParameterError, 582 IOPMNotYetInitialized = kIOPMNotYetInitialized 583 }; 584 585 586 // IOPMPowerSource class descriptive strings 587 // Power Source state is published as properties to the IORegistry under these 588 // keys. 589 #define kIOPMPSExternalConnectedKey "ExternalConnected" 590 #define kIOPMPSExternalChargeCapableKey "ExternalChargeCapable" 591 #define kIOPMPSBatteryInstalledKey "BatteryInstalled" 592 #define kIOPMPSIsChargingKey "IsCharging" 593 #define kIOPMFullyChargedKey "FullyCharged" 594 #define kIOPMPSAtWarnLevelKey "AtWarnLevel" 595 #define kIOPMPSAtCriticalLevelKey "AtCriticalLevel" 596 #define kIOPMPSCurrentCapacityKey "CurrentCapacity" 597 #define kIOPMPSMaxCapacityKey "MaxCapacity" 598 #define kIOPMPSDesignCapacityKey "DesignCapacity" 599 #define kIOPMPSTimeRemainingKey "TimeRemaining" 600 #define kIOPMPSAmperageKey "Amperage" 601 #define kIOPMPSVoltageKey "Voltage" 602 #define kIOPMPSCycleCountKey "CycleCount" 603 #define kIOPMPSMaxErrKey "MaxErr" 604 #define kIOPMPSAdapterInfoKey "AdapterInfo" 605 #define kIOPMPSLocationKey "Location" 606 #define kIOPMPSErrorConditionKey "ErrorCondition" 607 #define kIOPMPSManufacturerKey "Manufacturer" 608 #define kIOPMPSManufactureDateKey "ManufactureDate" 609 #define kIOPMPSModelKey "Model" 610 #define kIOPMPSSerialKey "Serial" 611 #define kIOPMDeviceNameKey "DeviceName" 612 #define kIOPMPSLegacyBatteryInfoKey "LegacyBatteryInfo" 613 #define kIOPMPSBatteryHealthKey "BatteryHealth" 614 #define kIOPMPSHealthConfidenceKey "HealthConfidence" 615 #define kIOPMPSCapacityEstimatedKey "CapacityEstimated" 616 #define kIOPMPSBatteryChargeStatusKey "ChargeStatus" 617 #define kIOPMPSBatteryTemperatureKey "Temperature" 618 #define kIOPMPSAdapterDetailsKey "AdapterDetails" 619 #define kIOPMPSChargerConfigurationKey "ChargerConfiguration" 620 621 // kIOPMPSBatteryChargeStatusKey may have one of the following values, or may have 622 // no value. If kIOPMBatteryChargeStatusKey has a NULL value (or no value) associated with it 623 // then charge is proceeding normally. If one of these battery charge status reasons is listed, 624 // then the charge may have been interrupted. 625 #define kIOPMBatteryChargeStatusTooHot "HighTemperature" 626 #define kIOPMBatteryChargeStatusTooCold "LowTemperature" 627 #define kIOPMBatteryChargeStatusTooHotOrCold "HighOrLowTemperature" 628 #define kIOPMBatteryChargeStatusGradient "BatteryTemperatureGradient" 629 630 // Definitions for battery location, in case of multiple batteries. 631 // A location of 0 is unspecified 632 // Location is undefined for single battery systems 633 enum { 634 kIOPMPSLocationLeft = 1001, 635 kIOPMPSLocationRight = 1002 636 }; 637 638 // Battery quality health types, specified by BatteryHealth and HealthConfidence 639 // properties in an IOPMPowerSource battery kext. 640 enum { 641 kIOPMUndefinedValue = 0, 642 kIOPMPoorValue = 1, 643 kIOPMFairValue = 2, 644 kIOPMGoodValue = 3 645 }; 646 647 // Keys for kIOPMPSAdapterDetailsKey dictionary 648 #define kIOPMPSAdapterDetailsIDKey "AdapterID" 649 #define kIOPMPSAdapterDetailsWattsKey "Watts" 650 #define kIOPMPSAdapterDetailsRevisionKey "AdapterRevision" 651 #define kIOPMPSAdapterDetailsSerialNumberKey "SerialNumber" 652 #define kIOPMPSAdapterDetailsFamilyKey "FamilyCode" 653 #define kIOPMPSAdapterDetailsAmperageKey "Current" 654 #define kIOPMPSAdapterDetailsDescriptionKey "Description" 655 #define kIOPMPSAdapterDetailsPMUConfigurationKey "PMUConfiguration" 656 #define kIOPMPSAdapterDetailsVoltage "AdapterVoltage" 657 #define kIOPMPSAdapterDetailsSourceIDKey "Source" 658 #define kIOPMPSAdapterDetailsErrorFlagsKey "ErrorFlags" 659 #define kIOPMPSAdapterDetailsSharedSourceKey "SharedSource" 660 #define kIOPMPSAdapterDetailsCloakedKey "CloakedSource" 661 662 // values for kIOPSPowerAdapterFamilyKey 663 enum { 664 kIOPSFamilyCodeDisconnected = 0, 665 kIOPSFamilyCodeUnsupported = kIOReturnUnsupported, 666 kIOPSFamilyCodeFirewire = iokit_family_err(sub_iokit_firewire, 0), 667 kIOPSFamilyCodeUSBHost = iokit_family_err(sub_iokit_usb, 0), 668 kIOPSFamilyCodeUSBHostSuspended = iokit_family_err(sub_iokit_usb, 1), 669 kIOPSFamilyCodeUSBDevice = iokit_family_err(sub_iokit_usb, 2), 670 kIOPSFamilyCodeUSBAdapter = iokit_family_err(sub_iokit_usb, 3), 671 kIOPSFamilyCodeUSBChargingPortDedicated = iokit_family_err(sub_iokit_usb, 4), 672 kIOPSFamilyCodeUSBChargingPortDownstream = iokit_family_err(sub_iokit_usb, 5), 673 kIOPSFamilyCodeUSBChargingPort = iokit_family_err(sub_iokit_usb, 6), 674 kIOPSFamilyCodeUSBUnknown = iokit_family_err(sub_iokit_usb, 7), 675 kIOPSFamilyCodeUSBCBrick = iokit_family_err(sub_iokit_usb, 8), 676 kIOPSFamilyCodeUSBCTypeC = iokit_family_err(sub_iokit_usb, 9), 677 kIOPSFamilyCodeUSBCPD = iokit_family_err(sub_iokit_usb, 10), 678 kIOPSFamilyCodeAC = iokit_family_err(sub_iokit_pmu, 0), 679 kIOPSFamilyCodeExternal = iokit_family_err(sub_iokit_pmu, 1), 680 kIOPSFamilyCodeExternal2 = iokit_family_err(sub_iokit_pmu, 2), 681 kIOPSFamilyCodeExternal3 = iokit_family_err(sub_iokit_pmu, 3), 682 kIOPSFamilyCodeExternal4 = iokit_family_err(sub_iokit_pmu, 4), 683 kIOPSFamilyCodeExternal5 = iokit_family_err(sub_iokit_pmu, 5), 684 kIOPSFamilyCodeExternal6 = iokit_family_err(sub_iokit_pmu, 6), 685 kIOPSFamilyCodeExternal7 = iokit_family_err(sub_iokit_pmu, 7), 686 kIOPSFamilyCodeExternal8 = iokit_family_err(sub_iokit_pmu, 8), 687 kIOPSFamilyCodeUnsupportedRegion = iokit_family_err(sub_iokit_pmu, 9), 688 }; 689 690 // values for kIOPMPSAdapterDetailsErrorFlagsKey 691 enum { 692 kIOPSAdapterErrorFlagNoErrors = 0, 693 kIOPSAdapterErrorFlagInsufficientAvailablePower = (1 << 1), 694 kIOPSAdapterErrorFlagForeignObjectDetected = (1 << 2), 695 kIOPSAdapterErrorFlagDeviceNeedsToBeRepositioned = (1 << 3), 696 }; 697 698 // Battery's time remaining estimate is invalid this long (seconds) after a wake 699 #define kIOPMPSInvalidWakeSecondsKey "BatteryInvalidWakeSeconds" 700 701 // Battery must wait this long (seconds) after being completely charged before 702 // the battery is settled. 703 #define kIOPMPSPostChargeWaitSecondsKey "PostChargeWaitSeconds" 704 705 // Battery must wait this long (seconds) after being completely discharged 706 // before the battery is settled. 707 #define kIOPMPSPostDishargeWaitSecondsKey "PostDischargeWaitSeconds" 708 709 710 /* CPU Power Management status keys 711 * Pass as arguments to IOPMrootDomain::systemPowerEventOccurred 712 * Or as arguments to IOPMSystemPowerEventOccurred() 713 * Or to decode the dictionary obtained from IOPMCopyCPUPowerStatus() 714 * These keys reflect restrictions placed on the CPU by the system 715 * to bring the CPU's power consumption within allowable thermal and 716 * power constraints. 717 */ 718 719 720 /* kIOPMGraphicsPowerLimitsKey 721 * The key representing the dictionary of graphics power limits. 722 * The dictionary contains the other kIOPMCPUPower keys & their associated 723 * values (e.g. Speed limit, Processor Count, and Schedule limits). 724 */ 725 #define kIOPMGraphicsPowerLimitsKey "Graphics_Power_Limits" 726 727 /* kIOPMGraphicsPowerLimitPerformanceKey 728 * The key representing the percent of overall performance made available 729 * by the graphics chip as a percentage (integer 0 - 100). 730 */ 731 #define kIOPMGraphicsPowerLimitPerformanceKey "Graphics_Power_Performance" 732 733 734 735 /* kIOPMCPUPowerLimitsKey 736 * The key representing the dictionary of CPU Power Limits. 737 * The dictionary contains the other kIOPMCPUPower keys & their associated 738 * values (e.g. Speed limit, Processor Count, and Schedule limits). 739 */ 740 #define kIOPMCPUPowerLimitsKey "CPU_Power_Limits" 741 742 /* kIOPMCPUPowerLimitProcessorSpeedKey defines the speed & voltage limits placed 743 * on the CPU. 744 * Represented as a percentage (0-100) of maximum CPU speed. 745 */ 746 #define kIOPMCPUPowerLimitProcessorSpeedKey "CPU_Speed_Limit" 747 748 /* kIOPMCPUPowerLimitProcessorCountKey reflects how many, if any, CPUs have been 749 * taken offline. Represented as an integer number of CPUs (0 - Max CPUs). 750 */ 751 #define kIOPMCPUPowerLimitProcessorCountKey "CPU_Available_CPUs" 752 753 /* kIOPMCPUPowerLimitSchedulerTimeKey represents the percentage (0-100) of CPU time 754 * available. 100% at normal operation. The OS may limit this time for a percentage 755 * less than 100%. 756 */ 757 #define kIOPMCPUPowerLimitSchedulerTimeKey "CPU_Scheduler_Limit" 758 759 760 /* Thermal Level Warning Key 761 * Indicates the thermal constraints placed on the system. This value may 762 * cause clients to action to consume fewer system resources. 763 * The value associated with this warning is defined by the platform. 764 */ 765 #define kIOPMThermalLevelWarningKey "Thermal_Level_Warning" 766 767 /* Thermal Warning Level values 768 * kIOPMThermalLevelNormal - under normal operating conditions 769 * kIOPMThermalLevelDanger - thermal pressure may cause system slowdown 770 * kIOPMThermalLevelCritical - thermal conditions may cause imminent shutdown 771 * 772 * The platform may define additional thermal levels if necessary. 773 * Platform specific values are defined from 100 and above 774 */ 775 enum { 776 kIOPMThermalLevelNormal = 0, 777 kIOPMThermalLevelDanger = 5, 778 kIOPMThermalLevelCritical = 10, 779 780 kIOPMThermalLevelWarning = 100, 781 kIOPMThermalLevelTrap = 110, 782 783 kIOPMThermalLevelUnknown = 255, 784 }; 785 786 #define kIOPMThermalWarningLevelNormal kIOPMThermalLevelNormal 787 #define kIOPMThermalWarningLevelDanger kIOPMThermalLevelWarning 788 #define kIOPMThermalWarningLevelCrisis kIOPMThermalLevelCritical 789 790 // PM Settings Controller setting types 791 // Settings types used primarily with: 792 // IOPMrootDomain::registerPMSettingController 793 // The values are identical to the similarly named keys for use in user space 794 // PM settings work. Those keys are defined in IOPMLibPrivate.h. 795 #define kIOPMSettingWakeOnRingKey "Wake On Modem Ring" 796 #define kIOPMSettingRestartOnPowerLossKey "Automatic Restart On Power Loss" 797 #define kIOPMSettingWakeOnACChangeKey "Wake On AC Change" 798 #define kIOPMSettingSleepOnPowerButtonKey "Sleep On Power Button" 799 #define kIOPMSettingWakeOnClamshellKey "Wake On Clamshell Open" 800 #define kIOPMSettingReduceBrightnessKey "ReduceBrightness" 801 #define kIOPMSettingDisplaySleepUsesDimKey "Display Sleep Uses Dim" 802 #define kIOPMSettingTimeZoneOffsetKey "TimeZoneOffsetSeconds" 803 #define kIOPMSettingMobileMotionModuleKey "MobileMotionModule" 804 #define kIOPMSettingGraphicsSwitchKey "GPUSwitch" 805 #define kIOPMSettingProModeControl "ProModeControl" 806 #define kIOPMSettingProModeDefer "ProModeDefer" 807 808 // Setting controlling drivers can register to receive scheduled wake data 809 // Either in "CF seconds" type, or structured calendar data in a formatted 810 // IOPMCalendarStruct defined below. 811 #define kIOPMSettingAutoWakeSecondsKey "wake" 812 #define kIOPMSettingAutoWakeCalendarKey "WakeByCalendarDate" 813 #define kIOPMSettingAutoPowerSecondsKey "poweron" 814 #define kIOPMSettingAutoPowerCalendarKey "PowerByCalendarDate" 815 816 // Debug seconds auto wake 817 // Used by sleep cycling debug tools 818 #define kIOPMSettingDebugWakeRelativeKey "WakeRelativeToSleep" 819 #define kIOPMSettingDebugPowerRelativeKey "PowerRelativeToShutdown" 820 821 // Maintenance wake calendar. 822 #define kIOPMSettingMaintenanceWakeCalendarKey "MaintenanceWakeCalendarDate" 823 824 825 struct IOPMCalendarStruct { 826 UInt32 year; 827 UInt8 month; 828 UInt8 day; 829 UInt8 hour; 830 UInt8 minute; 831 UInt8 second; 832 UInt8 selector; 833 }; 834 typedef struct IOPMCalendarStruct IOPMCalendarStruct; 835 836 // SetAggressiveness types 837 enum { 838 kPMGeneralAggressiveness = 0, 839 kPMMinutesToDim, 840 kPMMinutesToSpinDown, 841 kPMMinutesToSleep, 842 kPMEthernetWakeOnLANSettings, 843 kPMSetProcessorSpeed, 844 kPMPowerSource, 845 kPMMotionSensor, 846 kPMLastAggressivenessType 847 }; 848 #define kMaxType (kPMLastAggressivenessType-1) 849 850 // SetAggressiveness values for the kPMPowerSource aggressiveness type 851 enum { 852 kIOPMInternalPower = 1, 853 kIOPMExternalPower 854 }; 855 856 #define kIOREMSleepEnabledKey "REMSleepEnabled" 857 858 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo 859 #define kIOBatteryInfoKey "IOBatteryInfo" 860 #define kIOBatteryCurrentChargeKey "Current" 861 #define kIOBatteryCapacityKey "Capacity" 862 #define kIOBatteryFlagsKey "Flags" 863 #define kIOBatteryVoltageKey "Voltage" 864 #define kIOBatteryAmperageKey "Amperage" 865 #define kIOBatteryCycleCountKey "Cycle Count" 866 867 enum { 868 kIOBatteryInstalled = (1 << 2), 869 kIOBatteryCharge = (1 << 1), 870 kIOBatteryChargerConnect = (1 << 0) 871 }; 872 873 // Private power management message indicating battery data has changed 874 // Indicates new data resides in the IORegistry 875 #define kIOPMMessageBatteryStatusHasChanged iokit_family_msg(sub_iokit_pmu, 0x100) 876 877 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU 878 // through newer user space IOPMSchedulePowerEvent API 879 #define kIOPMUMessageLegacyAutoWake iokit_family_msg(sub_iokit_pmu, 0x200) 880 #define kIOPMUMessageLegacyAutoPower iokit_family_msg(sub_iokit_pmu, 0x210) 881 882 // For use with IOPMPowerSource bFlags 883 #define IOPM_POWER_SOURCE_REV 2 884 enum { 885 kIOPMACInstalled = kIOBatteryChargerConnect, 886 kIOPMBatteryCharging = kIOBatteryCharge, 887 kIOPMBatteryInstalled = kIOBatteryInstalled, 888 kIOPMUPSInstalled = (1 << 3), 889 kIOPMBatteryAtWarn = (1 << 4), 890 kIOPMBatteryDepleted = (1 << 5), 891 kIOPMACnoChargeCapability = (1 << 6), // AC adapter cannot charge battery 892 kIOPMRawLowBattery = (1 << 7), // used only by Platform Expert 893 kIOPMForceLowSpeed = (1 << 8), // set by Platfm Expert, chk'd by Pwr Plugin 894 kIOPMClosedClamshell = (1 << 9), // set by PMU - reflects state of the clamshell 895 kIOPMClamshellStateOnWake = (1 << 10) // used only by Platform Expert 896 }; 897 898 // ********************************************** 899 // Internal power management data structures 900 // ********************************************** 901 902 #if KERNEL && __cplusplus 903 class IOService; 904 905 enum { 906 kIOPowerEmergencyLevel = 1000 907 }; 908 909 enum { 910 kIOPMSubclassPolicy, 911 kIOPMSuperclassPolicy1 912 #ifdef KERNEL_PRIVATE 913 , kIOPMActivityTickleTypeAdvisory = 128 914 #endif 915 }; 916 917 struct stateChangeNote { 918 IOPMPowerFlags stateFlags; 919 unsigned long stateNum; 920 void * powerRef; 921 }; 922 typedef struct stateChangeNote stateChangeNote; 923 924 #endif /* KERNEL && __cplusplus */ 925 struct IOPowerStateChangeNotification { 926 void * powerRef; 927 unsigned long returnValue; 928 unsigned long stateNumber; 929 IOPMPowerFlags stateFlags; 930 }; 931 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification; 932 typedef IOPowerStateChangeNotification sleepWakeNote; 933 934 /*! @struct IOPMSystemCapabilityChangeParameters 935 * @abstract A structure describing a system capability change. 936 * @discussion A system capability change is a system level transition from a set 937 * of system capabilities to a new set of system capabilities. Power management 938 * sends a <code>kIOMessageSystemCapabilityChange</code> message and provides 939 * this structure as the message data (by reference) to 940 * <code>gIOPriorityPowerStateInterest</code> clients when system capability 941 * changes. 942 * @field notifyRef An identifier for this message notification. Clients with pending 943 * I/O can signal completion by calling <code>allowPowerChange()</code> with this 944 * value as the argument. Clients that are able to process the notification 945 * synchronously should ignore this field. 946 * @field maxWaitForReply A return value to the caller indicating the maximum time in 947 * microseconds to wait for the <code>allowPowerChange()</code> call. The default 948 * value is zero, which indicates the client processing has finished, and power 949 * management should not wait for an <code>allowPowerChange()</code> call. 950 * @field changeFlags Flags will be set to indicate whether the notification precedes 951 * the capability change (<code>kIOPMSystemCapabilityWillChange</code>), or after 952 * the capability change has occurred (<code>kIOPMSystemCapabilityDidChange</code>). 953 * @field __reserved1 Set to zero. 954 * @field fromCapabilities The system capabilities at the start of the transition. 955 * @field toCapabilities The system capabilities at the end of the transition. 956 * @field __reserved2 Set to zero. 957 */ 958 struct IOPMSystemCapabilityChangeParameters { 959 uint32_t notifyRef; 960 uint32_t maxWaitForReply; 961 uint32_t changeFlags; 962 uint32_t __reserved1; 963 uint32_t fromCapabilities; 964 uint32_t toCapabilities; 965 uint32_t __reserved2[4]; 966 }; 967 968 /*! @enum IOPMSystemCapabilityChangeFlags 969 * @constant kIOPMSystemCapabilityWillChange Indicates the system capability will change. 970 * @constant kIOPMSystemCapabilityDidChange Indicates the system capability has changed. 971 */ 972 enum { 973 kIOPMSystemCapabilityWillChange = 0x01, 974 kIOPMSystemCapabilityDidChange = 0x02 975 }; 976 977 enum { 978 kIOPMSystemCapabilityCPU = 0x01, 979 kIOPMSystemCapabilityGraphics = 0x02, 980 kIOPMSystemCapabilityAudio = 0x04, 981 kIOPMSystemCapabilityNetwork = 0x08, 982 kIOPMSystemCapabilityAOT = 0x10, 983 }; 984 985 #endif /* ! _IOKIT_IOPM_H */ 986