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 376 /* kIOPMAssertionsDriverKey 377 * This kIOPMrootDomain key refers to a CFNumberRef property, containing 378 * a bitfield describing the aggregate PM assertion levels. 379 * Example: A value of 0 indicates that no driver has asserted anything. 380 * Or, a value of <link>kIOPMDriverAssertionCPUBit</link> 381 * indicates that a driver (or drivers) have asserted a need for CPU and video. 382 */ 383 #define kIOPMAssertionsDriverKey "DriverPMAssertions" 384 385 /* kIOPMAssertionsDriverKey 386 * This kIOPMrootDomain key refers to a CFNumberRef property, containing 387 * a bitfield describing the aggregate PM assertion levels. 388 * Example: A value of 0 indicates that no driver has asserted anything. 389 * Or, a value of <link>kIOPMDriverAssertionCPUBit</link> 390 * indicates that a driver (or drivers) have asserted a need for CPU and video. 391 */ 392 #define kIOPMAssertionsDriverDetailedKey "DriverPMAssertionsDetailed" 393 394 /******************************************************************************* 395 * 396 * Kernel Driver assertion detailed dictionary keys 397 * 398 * Keys decode the Array & dictionary data structure under IOPMrootDomain property 399 * kIOPMAssertionsDriverKey. 400 * 401 */ 402 #define kIOPMDriverAssertionIDKey "ID" 403 #define kIOPMDriverAssertionCreatedTimeKey "CreatedTime" 404 #define kIOPMDriverAssertionModifiedTimeKey "ModifiedTime" 405 #define kIOPMDriverAssertionOwnerStringKey "Owner" 406 #define kIOPMDriverAssertionOwnerServiceKey "ServicePtr" 407 #define kIOPMDriverAssertionRegistryEntryIDKey "RegistryEntryID" 408 #define kIOPMDriverAssertionLevelKey "Level" 409 #define kIOPMDriverAssertionAssertedKey "Assertions" 410 411 /******************************************************************************* 412 * 413 * Root Domain general interest messages 414 * 415 * Available by registering for interest type 'gIOGeneralInterest' 416 * on IOPMrootDomain. 417 * 418 ******************************************************************************/ 419 420 /* kIOPMMessageClamshellStateChange 421 * Delivered as a general interest notification on the IOPMrootDomain 422 * IOPMrootDomain sends this message when state of either AppleClamshellState 423 * or AppleClamshellCausesSleep changes. If this clamshell change results in 424 * a sleep, the sleep will initiate soon AFTER delivery of this message. 425 * The state of both variables is encoded in a bitfield argument sent with 426 * the message. Check bits 0 and 1 using kClamshellStateBit & kClamshellSleepBit 427 */ 428 enum { 429 kClamshellStateBit = (1 << 0), 430 kClamshellSleepBit = (1 << 1) 431 }; 432 433 #define kIOPMMessageClamshellStateChange \ 434 iokit_family_msg(sub_iokit_powermanagement, 0x100) 435 436 /* kIOPMMessageFeatureChange 437 * Delivered when the set of supported features ("Supported Features" dictionary 438 * under IOPMrootDomain registry) changes in some way. Typically addition or 439 * removal of a supported feature. 440 * RootDomain passes no argument with this message. 441 */ 442 #define kIOPMMessageFeatureChange \ 443 iokit_family_msg(sub_iokit_powermanagement, 0x110) 444 445 /* kIOPMMessageInflowDisableCancelled 446 * The battery has drained completely to its "Fully Discharged" state. 447 * If a user process has disabled battery inflow for battery 448 * calibration, we forcibly re-enable Inflow at this point. 449 * If inflow HAS been forcibly re-enabled, bit 0 450 * (kInflowForciblyEnabledBit) will be set. 451 */ 452 enum { 453 kInflowForciblyEnabledBit = (1 << 0) 454 }; 455 456 /* kIOPMMessageInternalBatteryFullyDischarged 457 * The battery has drained completely to its "Fully Discharged" state. 458 */ 459 #define kIOPMMessageInternalBatteryFullyDischarged \ 460 iokit_family_msg(sub_iokit_powermanagement, 0x120) 461 462 /* kIOPMMessageSystemPowerEventOccurred 463 * Some major system thermal property has changed, and interested clients may 464 * modify their behavior. 465 */ 466 #define kIOPMMessageSystemPowerEventOccurred \ 467 iokit_family_msg(sub_iokit_powermanagement, 0x130) 468 469 /* kIOPMMessageSleepWakeUUIDChange 470 * Either a new SleepWakeUUID has been specified at the beginning of a sleep, 471 * or we're removing the existing property upon completion of a wakeup. 472 */ 473 #define kIOPMMessageSleepWakeUUIDChange \ 474 iokit_family_msg(sub_iokit_powermanagement, 0x140) 475 476 /* kIOPMMessageSleepWakeUUIDSet 477 * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when 478 * a new UUID has been specified. 479 */ 480 #define kIOPMMessageSleepWakeUUIDSet ((void *)1) 481 482 /* kIOPMMessageSleepWakeUUIDCleared 483 * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when 484 * the current UUID has been removed. 485 */ 486 #define kIOPMMessageSleepWakeUUIDCleared ((void *)NULL) 487 488 /*! kIOPMMessageDriverAssertionsChanged 489 * Sent when kernel PM driver assertions have changed. 490 */ 491 #define kIOPMMessageDriverAssertionsChanged \ 492 iokit_family_msg(sub_iokit_powermanagement, 0x150) 493 494 /*! kIOPMMessageDarkWakeThermalEmergency 495 * Sent when machine becomes unsustainably warm in DarkWake. 496 * Kernel PM might choose to put the machine back to sleep right after. 497 */ 498 #define kIOPMMessageDarkWakeThermalEmergency \ 499 iokit_family_msg(sub_iokit_powermanagement, 0x160) 500 501 /******************************************************************************* 502 * 503 * Power commands issued to root domain 504 * Use with IOPMrootDomain::receivePowerNotification() 505 * 506 * These commands are issued from system drivers only: 507 * ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily 508 * 509 * TODO: deprecate kIOPMAllowSleep and kIOPMPreventSleep 510 ******************************************************************************/ 511 enum { 512 kIOPMSleepNow = (1 << 0),// put machine to sleep now 513 kIOPMAllowSleep = (1 << 1),// allow idle sleep 514 kIOPMPreventSleep = (1 << 2),// do not allow idle sleep 515 kIOPMPowerButton = (1 << 3),// power button was pressed 516 kIOPMClamshellClosed = (1 << 4),// clamshell was closed 517 kIOPMPowerEmergency = (1 << 5),// battery dangerously low 518 kIOPMDisableClamshell = (1 << 6),// do not sleep on clamshell closure 519 kIOPMEnableClamshell = (1 << 7),// sleep on clamshell closure 520 kIOPMProcessorSpeedChange = (1 << 8),// change the processor speed 521 kIOPMOverTemp = (1 << 9),// system dangerously hot 522 kIOPMClamshellOpened = (1 << 10),// clamshell was opened 523 kIOPMDWOverTemp = (1 << 11),// DarkWake thermal limits exceeded. 524 kIOPMPowerButtonUp = (1 << 12),// Power button up 525 kIOPMProModeEngaged = (1 << 13),// Fans entered 'ProMode' 526 kIOPMProModeDisengaged = (1 << 14) // Fans exited 'ProMode' 527 }; 528 529 530 /******************************************************************************* 531 * 532 * Power Management Return Codes 533 * 534 ******************************************************************************/ 535 enum { 536 kIOPMNoErr = 0, 537 538 // Returned by driver's setPowerState(), powerStateWillChangeTo(), 539 // powerStateDidChangeTo(), or acknowledgeSetPowerState() to 540 // implicitly acknowledge power change upon function return. 541 kIOPMAckImplied = 0, 542 543 // Deprecated 544 kIOPMWillAckLater = 1, 545 546 // Returned by requestPowerDomainState() to indicate 547 // unrecognized specification parameter. 548 kIOPMBadSpecification = 4, 549 550 // Returned by requestPowerDomainState() to indicate 551 // no power state matches search specification. 552 kIOPMNoSuchState = 5, 553 554 // Deprecated 555 kIOPMCannotRaisePower = 6, 556 557 // Deprecated 558 kIOPMParameterError = 7, 559 560 // Returned when power management state is accessed 561 // before driver has called PMinit(). 562 kIOPMNotYetInitialized = 8, 563 564 // And the old constants; deprecated 565 IOPMNoErr = kIOPMNoErr, 566 IOPMAckImplied = kIOPMAckImplied, 567 IOPMWillAckLater = kIOPMWillAckLater, 568 IOPMBadSpecification = kIOPMBadSpecification, 569 IOPMNoSuchState = kIOPMNoSuchState, 570 IOPMCannotRaisePower = kIOPMCannotRaisePower, 571 IOPMParameterError = kIOPMParameterError, 572 IOPMNotYetInitialized = kIOPMNotYetInitialized 573 }; 574 575 576 // IOPMPowerSource class descriptive strings 577 // Power Source state is published as properties to the IORegistry under these 578 // keys. 579 #define kIOPMPSExternalConnectedKey "ExternalConnected" 580 #define kIOPMPSExternalChargeCapableKey "ExternalChargeCapable" 581 #define kIOPMPSBatteryInstalledKey "BatteryInstalled" 582 #define kIOPMPSIsChargingKey "IsCharging" 583 #define kIOPMFullyChargedKey "FullyCharged" 584 #define kIOPMPSAtWarnLevelKey "AtWarnLevel" 585 #define kIOPMPSAtCriticalLevelKey "AtCriticalLevel" 586 #define kIOPMPSCurrentCapacityKey "CurrentCapacity" 587 #define kIOPMPSMaxCapacityKey "MaxCapacity" 588 #define kIOPMPSDesignCapacityKey "DesignCapacity" 589 #define kIOPMPSTimeRemainingKey "TimeRemaining" 590 #define kIOPMPSAmperageKey "Amperage" 591 #define kIOPMPSVoltageKey "Voltage" 592 #define kIOPMPSCycleCountKey "CycleCount" 593 #define kIOPMPSMaxErrKey "MaxErr" 594 #define kIOPMPSAdapterInfoKey "AdapterInfo" 595 #define kIOPMPSLocationKey "Location" 596 #define kIOPMPSErrorConditionKey "ErrorCondition" 597 #define kIOPMPSManufacturerKey "Manufacturer" 598 #define kIOPMPSManufactureDateKey "ManufactureDate" 599 #define kIOPMPSModelKey "Model" 600 #define kIOPMPSSerialKey "Serial" 601 #define kIOPMDeviceNameKey "DeviceName" 602 #define kIOPMPSLegacyBatteryInfoKey "LegacyBatteryInfo" 603 #define kIOPMPSBatteryHealthKey "BatteryHealth" 604 #define kIOPMPSHealthConfidenceKey "HealthConfidence" 605 #define kIOPMPSCapacityEstimatedKey "CapacityEstimated" 606 #define kIOPMPSBatteryChargeStatusKey "ChargeStatus" 607 #define kIOPMPSBatteryTemperatureKey "Temperature" 608 #define kIOPMPSAdapterDetailsKey "AdapterDetails" 609 #define kIOPMPSChargerConfigurationKey "ChargerConfiguration" 610 611 // kIOPMPSBatteryChargeStatusKey may have one of the following values, or may have 612 // no value. If kIOPMBatteryChargeStatusKey has a NULL value (or no value) associated with it 613 // then charge is proceeding normally. If one of these battery charge status reasons is listed, 614 // then the charge may have been interrupted. 615 #define kIOPMBatteryChargeStatusTooHot "HighTemperature" 616 #define kIOPMBatteryChargeStatusTooCold "LowTemperature" 617 #define kIOPMBatteryChargeStatusTooHotOrCold "HighOrLowTemperature" 618 #define kIOPMBatteryChargeStatusGradient "BatteryTemperatureGradient" 619 620 // Definitions for battery location, in case of multiple batteries. 621 // A location of 0 is unspecified 622 // Location is undefined for single battery systems 623 enum { 624 kIOPMPSLocationLeft = 1001, 625 kIOPMPSLocationRight = 1002 626 }; 627 628 // Battery quality health types, specified by BatteryHealth and HealthConfidence 629 // properties in an IOPMPowerSource battery kext. 630 enum { 631 kIOPMUndefinedValue = 0, 632 kIOPMPoorValue = 1, 633 kIOPMFairValue = 2, 634 kIOPMGoodValue = 3 635 }; 636 637 // Keys for kIOPMPSAdapterDetailsKey dictionary 638 #define kIOPMPSAdapterDetailsIDKey "AdapterID" 639 #define kIOPMPSAdapterDetailsWattsKey "Watts" 640 #define kIOPMPSAdapterDetailsRevisionKey "AdapterRevision" 641 #define kIOPMPSAdapterDetailsSerialNumberKey "SerialNumber" 642 #define kIOPMPSAdapterDetailsFamilyKey "FamilyCode" 643 #define kIOPMPSAdapterDetailsAmperageKey "Current" 644 #define kIOPMPSAdapterDetailsDescriptionKey "Description" 645 #define kIOPMPSAdapterDetailsPMUConfigurationKey "PMUConfiguration" 646 #define kIOPMPSAdapterDetailsVoltage "AdapterVoltage" 647 #define kIOPMPSAdapterDetailsSourceIDKey "Source" 648 #define kIOPMPSAdapterDetailsErrorFlagsKey "ErrorFlags" 649 #define kIOPMPSAdapterDetailsSharedSourceKey "SharedSource" 650 #define kIOPMPSAdapterDetailsCloakedKey "CloakedSource" 651 652 // values for kIOPSPowerAdapterFamilyKey 653 enum { 654 kIOPSFamilyCodeDisconnected = 0, 655 kIOPSFamilyCodeUnsupported = kIOReturnUnsupported, 656 kIOPSFamilyCodeFirewire = iokit_family_err(sub_iokit_firewire, 0), 657 kIOPSFamilyCodeUSBHost = iokit_family_err(sub_iokit_usb, 0), 658 kIOPSFamilyCodeUSBHostSuspended = iokit_family_err(sub_iokit_usb, 1), 659 kIOPSFamilyCodeUSBDevice = iokit_family_err(sub_iokit_usb, 2), 660 kIOPSFamilyCodeUSBAdapter = iokit_family_err(sub_iokit_usb, 3), 661 kIOPSFamilyCodeUSBChargingPortDedicated = iokit_family_err(sub_iokit_usb, 4), 662 kIOPSFamilyCodeUSBChargingPortDownstream = iokit_family_err(sub_iokit_usb, 5), 663 kIOPSFamilyCodeUSBChargingPort = iokit_family_err(sub_iokit_usb, 6), 664 kIOPSFamilyCodeUSBUnknown = iokit_family_err(sub_iokit_usb, 7), 665 kIOPSFamilyCodeUSBCBrick = iokit_family_err(sub_iokit_usb, 8), 666 kIOPSFamilyCodeUSBCTypeC = iokit_family_err(sub_iokit_usb, 9), 667 kIOPSFamilyCodeUSBCPD = iokit_family_err(sub_iokit_usb, 10), 668 kIOPSFamilyCodeAC = iokit_family_err(sub_iokit_pmu, 0), 669 kIOPSFamilyCodeExternal = iokit_family_err(sub_iokit_pmu, 1), 670 kIOPSFamilyCodeExternal2 = iokit_family_err(sub_iokit_pmu, 2), 671 kIOPSFamilyCodeExternal3 = iokit_family_err(sub_iokit_pmu, 3), 672 kIOPSFamilyCodeExternal4 = iokit_family_err(sub_iokit_pmu, 4), 673 kIOPSFamilyCodeExternal5 = iokit_family_err(sub_iokit_pmu, 5), 674 kIOPSFamilyCodeExternal6 = iokit_family_err(sub_iokit_pmu, 6), 675 kIOPSFamilyCodeExternal7 = iokit_family_err(sub_iokit_pmu, 7), 676 kIOPSFamilyCodeExternal8 = iokit_family_err(sub_iokit_pmu, 8), 677 kIOPSFamilyCodeUnsupportedRegion = iokit_family_err(sub_iokit_pmu, 9), 678 }; 679 680 // values for kIOPMPSAdapterDetailsErrorFlagsKey 681 enum { 682 kIOPSAdapterErrorFlagNoErrors = 0, 683 kIOPSAdapterErrorFlagInsufficientAvailablePower = (1 << 1), 684 kIOPSAdapterErrorFlagForeignObjectDetected = (1 << 2), 685 kIOPSAdapterErrorFlagDeviceNeedsToBeRepositioned = (1 << 3), 686 }; 687 688 // Battery's time remaining estimate is invalid this long (seconds) after a wake 689 #define kIOPMPSInvalidWakeSecondsKey "BatteryInvalidWakeSeconds" 690 691 // Battery must wait this long (seconds) after being completely charged before 692 // the battery is settled. 693 #define kIOPMPSPostChargeWaitSecondsKey "PostChargeWaitSeconds" 694 695 // Battery must wait this long (seconds) after being completely discharged 696 // before the battery is settled. 697 #define kIOPMPSPostDishargeWaitSecondsKey "PostDischargeWaitSeconds" 698 699 700 /* CPU Power Management status keys 701 * Pass as arguments to IOPMrootDomain::systemPowerEventOccurred 702 * Or as arguments to IOPMSystemPowerEventOccurred() 703 * Or to decode the dictionary obtained from IOPMCopyCPUPowerStatus() 704 * These keys reflect restrictions placed on the CPU by the system 705 * to bring the CPU's power consumption within allowable thermal and 706 * power constraints. 707 */ 708 709 710 /* kIOPMGraphicsPowerLimitsKey 711 * The key representing the dictionary of graphics power limits. 712 * The dictionary contains the other kIOPMCPUPower keys & their associated 713 * values (e.g. Speed limit, Processor Count, and Schedule limits). 714 */ 715 #define kIOPMGraphicsPowerLimitsKey "Graphics_Power_Limits" 716 717 /* kIOPMGraphicsPowerLimitPerformanceKey 718 * The key representing the percent of overall performance made available 719 * by the graphics chip as a percentage (integer 0 - 100). 720 */ 721 #define kIOPMGraphicsPowerLimitPerformanceKey "Graphics_Power_Performance" 722 723 724 725 /* kIOPMCPUPowerLimitsKey 726 * The key representing the dictionary of CPU Power Limits. 727 * The dictionary contains the other kIOPMCPUPower keys & their associated 728 * values (e.g. Speed limit, Processor Count, and Schedule limits). 729 */ 730 #define kIOPMCPUPowerLimitsKey "CPU_Power_Limits" 731 732 /* kIOPMCPUPowerLimitProcessorSpeedKey defines the speed & voltage limits placed 733 * on the CPU. 734 * Represented as a percentage (0-100) of maximum CPU speed. 735 */ 736 #define kIOPMCPUPowerLimitProcessorSpeedKey "CPU_Speed_Limit" 737 738 /* kIOPMCPUPowerLimitProcessorCountKey reflects how many, if any, CPUs have been 739 * taken offline. Represented as an integer number of CPUs (0 - Max CPUs). 740 */ 741 #define kIOPMCPUPowerLimitProcessorCountKey "CPU_Available_CPUs" 742 743 /* kIOPMCPUPowerLimitSchedulerTimeKey represents the percentage (0-100) of CPU time 744 * available. 100% at normal operation. The OS may limit this time for a percentage 745 * less than 100%. 746 */ 747 #define kIOPMCPUPowerLimitSchedulerTimeKey "CPU_Scheduler_Limit" 748 749 750 /* Thermal Level Warning Key 751 * Indicates the thermal constraints placed on the system. This value may 752 * cause clients to action to consume fewer system resources. 753 * The value associated with this warning is defined by the platform. 754 */ 755 #define kIOPMThermalLevelWarningKey "Thermal_Level_Warning" 756 757 /* Thermal Warning Level values 758 * kIOPMThermalLevelNormal - under normal operating conditions 759 * kIOPMThermalLevelDanger - thermal pressure may cause system slowdown 760 * kIOPMThermalLevelCritical - thermal conditions may cause imminent shutdown 761 * 762 * The platform may define additional thermal levels if necessary. 763 * Platform specific values are defined from 100 and above 764 */ 765 enum { 766 kIOPMThermalLevelNormal = 0, 767 kIOPMThermalLevelDanger = 5, 768 kIOPMThermalLevelCritical = 10, 769 770 kIOPMThermalLevelWarning = 100, 771 kIOPMThermalLevelTrap = 110, 772 773 kIOPMThermalLevelUnknown = 255, 774 }; 775 776 #define kIOPMThermalWarningLevelNormal kIOPMThermalLevelNormal 777 #define kIOPMThermalWarningLevelDanger kIOPMThermalLevelWarning 778 #define kIOPMThermalWarningLevelCrisis kIOPMThermalLevelCritical 779 780 // PM Settings Controller setting types 781 // Settings types used primarily with: 782 // IOPMrootDomain::registerPMSettingController 783 // The values are identical to the similarly named keys for use in user space 784 // PM settings work. Those keys are defined in IOPMLibPrivate.h. 785 #define kIOPMSettingWakeOnRingKey "Wake On Modem Ring" 786 #define kIOPMSettingRestartOnPowerLossKey "Automatic Restart On Power Loss" 787 #define kIOPMSettingWakeOnACChangeKey "Wake On AC Change" 788 #define kIOPMSettingSleepOnPowerButtonKey "Sleep On Power Button" 789 #define kIOPMSettingWakeOnClamshellKey "Wake On Clamshell Open" 790 #define kIOPMSettingReduceBrightnessKey "ReduceBrightness" 791 #define kIOPMSettingDisplaySleepUsesDimKey "Display Sleep Uses Dim" 792 #define kIOPMSettingTimeZoneOffsetKey "TimeZoneOffsetSeconds" 793 #define kIOPMSettingMobileMotionModuleKey "MobileMotionModule" 794 #define kIOPMSettingGraphicsSwitchKey "GPUSwitch" 795 #define kIOPMSettingProModeControl "ProModeControl" 796 #define kIOPMSettingProModeDefer "ProModeDefer" 797 798 // Setting controlling drivers can register to receive scheduled wake data 799 // Either in "CF seconds" type, or structured calendar data in a formatted 800 // IOPMCalendarStruct defined below. 801 #define kIOPMSettingAutoWakeSecondsKey "wake" 802 #define kIOPMSettingAutoWakeCalendarKey "WakeByCalendarDate" 803 #define kIOPMSettingAutoPowerSecondsKey "poweron" 804 #define kIOPMSettingAutoPowerCalendarKey "PowerByCalendarDate" 805 806 // Debug seconds auto wake 807 // Used by sleep cycling debug tools 808 #define kIOPMSettingDebugWakeRelativeKey "WakeRelativeToSleep" 809 #define kIOPMSettingDebugPowerRelativeKey "PowerRelativeToShutdown" 810 811 // Maintenance wake calendar. 812 #define kIOPMSettingMaintenanceWakeCalendarKey "MaintenanceWakeCalendarDate" 813 814 815 struct IOPMCalendarStruct { 816 UInt32 year; 817 UInt8 month; 818 UInt8 day; 819 UInt8 hour; 820 UInt8 minute; 821 UInt8 second; 822 UInt8 selector; 823 }; 824 typedef struct IOPMCalendarStruct IOPMCalendarStruct; 825 826 // SetAggressiveness types 827 enum { 828 kPMGeneralAggressiveness = 0, 829 kPMMinutesToDim, 830 kPMMinutesToSpinDown, 831 kPMMinutesToSleep, 832 kPMEthernetWakeOnLANSettings, 833 kPMSetProcessorSpeed, 834 kPMPowerSource, 835 kPMMotionSensor, 836 kPMLastAggressivenessType 837 }; 838 #define kMaxType (kPMLastAggressivenessType-1) 839 840 // SetAggressiveness values for the kPMPowerSource aggressiveness type 841 enum { 842 kIOPMInternalPower = 1, 843 kIOPMExternalPower 844 }; 845 846 #define kIOREMSleepEnabledKey "REMSleepEnabled" 847 848 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo 849 #define kIOBatteryInfoKey "IOBatteryInfo" 850 #define kIOBatteryCurrentChargeKey "Current" 851 #define kIOBatteryCapacityKey "Capacity" 852 #define kIOBatteryFlagsKey "Flags" 853 #define kIOBatteryVoltageKey "Voltage" 854 #define kIOBatteryAmperageKey "Amperage" 855 #define kIOBatteryCycleCountKey "Cycle Count" 856 857 enum { 858 kIOBatteryInstalled = (1 << 2), 859 kIOBatteryCharge = (1 << 1), 860 kIOBatteryChargerConnect = (1 << 0) 861 }; 862 863 // Private power management message indicating battery data has changed 864 // Indicates new data resides in the IORegistry 865 #define kIOPMMessageBatteryStatusHasChanged iokit_family_msg(sub_iokit_pmu, 0x100) 866 867 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU 868 // through newer user space IOPMSchedulePowerEvent API 869 #define kIOPMUMessageLegacyAutoWake iokit_family_msg(sub_iokit_pmu, 0x200) 870 #define kIOPMUMessageLegacyAutoPower iokit_family_msg(sub_iokit_pmu, 0x210) 871 872 // For use with IOPMPowerSource bFlags 873 #define IOPM_POWER_SOURCE_REV 2 874 enum { 875 kIOPMACInstalled = kIOBatteryChargerConnect, 876 kIOPMBatteryCharging = kIOBatteryCharge, 877 kIOPMBatteryInstalled = kIOBatteryInstalled, 878 kIOPMUPSInstalled = (1 << 3), 879 kIOPMBatteryAtWarn = (1 << 4), 880 kIOPMBatteryDepleted = (1 << 5), 881 kIOPMACnoChargeCapability = (1 << 6), // AC adapter cannot charge battery 882 kIOPMRawLowBattery = (1 << 7), // used only by Platform Expert 883 kIOPMForceLowSpeed = (1 << 8), // set by Platfm Expert, chk'd by Pwr Plugin 884 kIOPMClosedClamshell = (1 << 9), // set by PMU - reflects state of the clamshell 885 kIOPMClamshellStateOnWake = (1 << 10) // used only by Platform Expert 886 }; 887 888 // ********************************************** 889 // Internal power management data structures 890 // ********************************************** 891 892 #if KERNEL && __cplusplus 893 class IOService; 894 895 enum { 896 kIOPowerEmergencyLevel = 1000 897 }; 898 899 enum { 900 kIOPMSubclassPolicy, 901 kIOPMSuperclassPolicy1 902 #ifdef KERNEL_PRIVATE 903 , kIOPMActivityTickleTypeAdvisory = 128 904 #endif 905 }; 906 907 struct stateChangeNote { 908 IOPMPowerFlags stateFlags; 909 unsigned long stateNum; 910 void * powerRef; 911 }; 912 typedef struct stateChangeNote stateChangeNote; 913 914 #endif /* KERNEL && __cplusplus */ 915 struct IOPowerStateChangeNotification { 916 void * powerRef; 917 unsigned long returnValue; 918 unsigned long stateNumber; 919 IOPMPowerFlags stateFlags; 920 }; 921 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification; 922 typedef IOPowerStateChangeNotification sleepWakeNote; 923 924 /*! @struct IOPMSystemCapabilityChangeParameters 925 * @abstract A structure describing a system capability change. 926 * @discussion A system capability change is a system level transition from a set 927 * of system capabilities to a new set of system capabilities. Power management 928 * sends a <code>kIOMessageSystemCapabilityChange</code> message and provides 929 * this structure as the message data (by reference) to 930 * <code>gIOPriorityPowerStateInterest</code> clients when system capability 931 * changes. 932 * @field notifyRef An identifier for this message notification. Clients with pending 933 * I/O can signal completion by calling <code>allowPowerChange()</code> with this 934 * value as the argument. Clients that are able to process the notification 935 * synchronously should ignore this field. 936 * @field maxWaitForReply A return value to the caller indicating the maximum time in 937 * microseconds to wait for the <code>allowPowerChange()</code> call. The default 938 * value is zero, which indicates the client processing has finished, and power 939 * management should not wait for an <code>allowPowerChange()</code> call. 940 * @field changeFlags Flags will be set to indicate whether the notification precedes 941 * the capability change (<code>kIOPMSystemCapabilityWillChange</code>), or after 942 * the capability change has occurred (<code>kIOPMSystemCapabilityDidChange</code>). 943 * @field __reserved1 Set to zero. 944 * @field fromCapabilities The system capabilities at the start of the transition. 945 * @field toCapabilities The system capabilities at the end of the transition. 946 * @field __reserved2 Set to zero. 947 */ 948 struct IOPMSystemCapabilityChangeParameters { 949 uint32_t notifyRef; 950 uint32_t maxWaitForReply; 951 uint32_t changeFlags; 952 uint32_t __reserved1; 953 uint32_t fromCapabilities; 954 uint32_t toCapabilities; 955 uint32_t __reserved2[4]; 956 }; 957 958 /*! @enum IOPMSystemCapabilityChangeFlags 959 * @constant kIOPMSystemCapabilityWillChange Indicates the system capability will change. 960 * @constant kIOPMSystemCapabilityDidChange Indicates the system capability has changed. 961 */ 962 enum { 963 kIOPMSystemCapabilityWillChange = 0x01, 964 kIOPMSystemCapabilityDidChange = 0x02 965 }; 966 967 enum { 968 kIOPMSystemCapabilityCPU = 0x01, 969 kIOPMSystemCapabilityGraphics = 0x02, 970 kIOPMSystemCapabilityAudio = 0x04, 971 kIOPMSystemCapabilityNetwork = 0x08 972 }; 973 974 #endif /* ! _IOKIT_IOPM_H */ 975