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