iokit/IOKit/pwr_mgt/IOPM.h

   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     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  */
 121 enum {
 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  */
 136 enum {
 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  */
 154 enum {
 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
 169 enum {
 170     kIOPMNextHigherState        = 1,
 171     kIOPMHighestState           = 2,
 172     kIOPMNextLowerState         = 3,
 173     kIOPMLowestState            = 4
 174 };
 175
 176 enum {
 177     IOPMNextHigherState         = kIOPMNextHigherState,
 178     IOPMHighestState            = kIOPMHighestState,
 179     IOPMNextLowerState          = kIOPMNextLowerState,
 180     IOPMLowestState             = kIOPMLowestState
 181 };
 182
 183 // Internal commands used by power managment command queue
 184 enum {
 185     kIOPMBroadcastAggressiveness = 1,
 186     kIOPMUnidleDevice
 187 };
 188
 189 // Power consumption unknown value
 190 enum {
 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  */
 299 enum {
 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  */
 400 enum {
 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  */
 424 enum {
 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  ******************************************************************************/
 483 enum {
 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  ******************************************************************************/
 504 enum {
 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
 592 enum {
 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.
 599 enum {
 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  *      kIOPMThermalLevelNormal   - under normal operating conditions
 687  *      kIOPMThermalLevelDanger   - thermal pressure may cause system slowdown
 688  *      kIOPMThermalLevelCritical - thermal conditions may cause imminent shutdown
 689  *
 690  * The platform may define additional thermal levels if necessary.
 691  * Platform specific values are defined from 100 and above
 692  */
 693 enum {
 694   kIOPMThermalLevelNormal    = 0,
 695   kIOPMThermalLevelDanger    = 5,
 696   kIOPMThermalLevelCritical  = 10,
 697
 698   kIOPMThermalLevelWarning = 100,
 699   kIOPMThermalLevelTrap    = 110,
 700
 701   kIOPMThermalLevelUnknown = 255,
 702 };
 703
 704 #define kIOPMThermalWarningLevelNormal kIOPMThermalLevelNormal
 705 #define kIOPMThermalWarningLevelDanger kIOPMThermalLevelWarning
 706 #define kIOPMThermalWarningLevelCrisis kIOPMThermalLevelCritical
 707
 708 // PM Settings Controller setting types
 709 // Settings types used primarily with:
 710 //      IOPMrootDomain::registerPMSettingController
 711 // The values are identical to the similarly named keys for use in user space
 712 // PM settings work. Those keys are defined in IOPMLibPrivate.h.
 713 #define kIOPMSettingWakeOnRingKey                   "Wake On Modem Ring"
 714 #define kIOPMSettingRestartOnPowerLossKey           "Automatic Restart On Power Loss"
 715 #define kIOPMSettingWakeOnACChangeKey               "Wake On AC Change"
 716 #define kIOPMSettingSleepOnPowerButtonKey           "Sleep On Power Button"
 717 #define kIOPMSettingWakeOnClamshellKey              "Wake On Clamshell Open"
 718 #define kIOPMSettingReduceBrightnessKey             "ReduceBrightness"
 719 #define kIOPMSettingDisplaySleepUsesDimKey          "Display Sleep Uses Dim"
 720 #define kIOPMSettingTimeZoneOffsetKey               "TimeZoneOffsetSeconds"
 721 #define kIOPMSettingMobileMotionModuleKey           "MobileMotionModule"
 722 #define kIOPMSettingGraphicsSwitchKey               "GPUSwitch"
 723
 724 // Setting controlling drivers can register to receive scheduled wake data
 725 // Either in "CF seconds" type, or structured calendar data in a formatted
 726 // IOPMCalendarStruct defined below.
 727 #define kIOPMSettingAutoWakeSecondsKey              "wake"
 728 #define kIOPMSettingAutoWakeCalendarKey             "WakeByCalendarDate"
 729 #define kIOPMSettingAutoPowerSecondsKey             "poweron"
 730 #define kIOPMSettingAutoPowerCalendarKey            "PowerByCalendarDate"
 731
 732 // Debug seconds auto wake
 733 // Used by sleep cycling debug tools
 734 #define kIOPMSettingDebugWakeRelativeKey            "WakeRelativeToSleep"
 735 #define kIOPMSettingDebugPowerRelativeKey           "PowerRelativeToShutdown"
 736
 737 // Maintenance wake calendar.
 738 #define kIOPMSettingMaintenanceWakeCalendarKey      "MaintenanceWakeCalendarDate"
 739
 740
 741 struct IOPMCalendarStruct {
 742     UInt32      year;
 743     UInt8       month;
 744     UInt8       day;
 745     UInt8       hour;
 746     UInt8       minute;
 747     UInt8       second;
 748     UInt8       selector;
 749 };
 750 typedef struct IOPMCalendarStruct IOPMCalendarStruct;
 751
 752 // SetAggressiveness types
 753 enum {
 754     kPMGeneralAggressiveness = 0,
 755     kPMMinutesToDim,
 756     kPMMinutesToSpinDown,
 757     kPMMinutesToSleep,
 758     kPMEthernetWakeOnLANSettings,
 759     kPMSetProcessorSpeed,
 760     kPMPowerSource,
 761     kPMMotionSensor,
 762     kPMLastAggressivenessType
 763 };
 764 #define kMaxType (kPMLastAggressivenessType-1)
 765
 766 // SetAggressiveness values for the kPMPowerSource aggressiveness type
 767 enum {
 768     kIOPMInternalPower = 1,
 769     kIOPMExternalPower
 770 };
 771
 772 #define kIOREMSleepEnabledKey               "REMSleepEnabled"
 773
 774 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo
 775 #define kIOBatteryInfoKey                   "IOBatteryInfo"
 776 #define kIOBatteryCurrentChargeKey          "Current"
 777 #define kIOBatteryCapacityKey               "Capacity"
 778 #define kIOBatteryFlagsKey                  "Flags"
 779 #define kIOBatteryVoltageKey                "Voltage"
 780 #define kIOBatteryAmperageKey               "Amperage"
 781 #define kIOBatteryCycleCountKey             "Cycle Count"
 782
 783 enum {
 784     kIOBatteryInstalled         = (1 << 2),
 785     kIOBatteryCharge            = (1 << 1),
 786     kIOBatteryChargerConnect    = (1 << 0)
 787 };
 788
 789 // Private power management message indicating battery data has changed
 790 // Indicates new data resides in the IORegistry
 791 #define kIOPMMessageBatteryStatusHasChanged         iokit_family_msg(sub_iokit_pmu, 0x100)
 792
 793 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU
 794 // through newer user space IOPMSchedulePowerEvent API
 795 #define kIOPMUMessageLegacyAutoWake                 iokit_family_msg(sub_iokit_pmu, 0x200)
 796 #define kIOPMUMessageLegacyAutoPower                iokit_family_msg(sub_iokit_pmu, 0x210)
 797
 798 // For use with IOPMPowerSource bFlags
 799 #define IOPM_POWER_SOURCE_REV   2
 800 enum {
 801   kIOPMACInstalled      = kIOBatteryChargerConnect,
 802   kIOPMBatteryCharging  = kIOBatteryCharge,
 803   kIOPMBatteryInstalled = kIOBatteryInstalled,
 804   kIOPMUPSInstalled     = (1<<3),
 805   kIOPMBatteryAtWarn    = (1<<4),
 806   kIOPMBatteryDepleted  = (1<<5),
 807   kIOPMACnoChargeCapability = (1<<6),     // AC adapter cannot charge battery
 808   kIOPMRawLowBattery    = (1<<7),         // used only by  Platform Expert
 809   kIOPMForceLowSpeed    = (1<<8),         // set by Platfm Expert, chk'd by Pwr Plugin
 810   kIOPMClosedClamshell  = (1<<9),         // set by PMU - reflects state of the clamshell
 811   kIOPMClamshellStateOnWake = (1<<10)     // used only by Platform Expert
 812 };
 813
 814 // **********************************************
 815 // Internal power management data structures
 816 // **********************************************
 817
 818 #if KERNEL && __cplusplus
 819 class IOService;
 820
 821 enum {
 822     kIOPowerEmergencyLevel = 1000
 823 };
 824
 825 enum {
 826     kIOPMSubclassPolicy,
 827     kIOPMSuperclassPolicy1
 828 #ifdef KERNEL_PRIVATE
 829     , kIOPMActivityTickleTypeAdvisory = 128
 830 #endif
 831 };
 832
 833 struct stateChangeNote {
 834     IOPMPowerFlags    stateFlags;
 835     unsigned long    stateNum;
 836     void *         powerRef;
 837 };
 838 typedef struct stateChangeNote stateChangeNote;
 839
 840 #endif /* KERNEL && __cplusplus */
 841 struct IOPowerStateChangeNotification {
 842     void *        powerRef;
 843     unsigned long    returnValue;
 844     unsigned long    stateNumber;
 845     IOPMPowerFlags    stateFlags;
 846 };
 847 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification;
 848 typedef IOPowerStateChangeNotification sleepWakeNote;
 849
 850 /*! @struct IOPMSystemCapabilityChangeParameters
 851     @abstract A structure describing a system capability change.
 852     @discussion A system capability change is a system level transition from a set
 853         of system capabilities to a new set of system capabilities. Power management
 854         sends a <code>kIOMessageSystemCapabilityChange</code> message and provides
 855         this structure as the message data (by reference) to
 856         <code>gIOPriorityPowerStateInterest</code> clients when system capability
 857         changes.
 858     @field notifyRef An identifier for this message notification. Clients with pending
 859         I/O can signal completion by calling <code>allowPowerChange()</code> with this
 860         value as the argument. Clients that are able to process the notification
 861         synchronously should ignore this field.
 862     @field maxWaitForReply A return value to the caller indicating the maximum time in
 863         microseconds to wait for the <code>allowPowerChange()</code> call. The default
 864         value is zero, which indicates the client processing has finished, and power
 865         management should not wait for an <code>allowPowerChange()</code> call.
 866     @field changeFlags Flags will be set to indicate whether the notification precedes
 867         the capability change (<code>kIOPMSystemCapabilityWillChange</code>), or after
 868         the capability change has occurred (<code>kIOPMSystemCapabilityDidChange</code>).
 869     @field __reserved1 Set to zero.
 870     @field fromCapabilities The system capabilities at the start of the transition.
 871     @field toCapabilities The system capabilities at the end of the transition.
 872     @field __reserved2 Set to zero.
 873  */
 874 struct IOPMSystemCapabilityChangeParameters {
 875     uint32_t    notifyRef;
 876     uint32_t    maxWaitForReply;
 877     uint32_t    changeFlags;
 878     uint32_t    __reserved1;
 879     uint32_t    fromCapabilities;
 880     uint32_t    toCapabilities;
 881     uint32_t    __reserved2[4];
 882 };
 883
 884 /*! @enum IOPMSystemCapabilityChangeFlags
 885     @constant kIOPMSystemCapabilityWillChange Indicates the system capability will change.
 886     @constant kIOPMSystemCapabilityDidChange Indicates the system capability has changed.
 887 */
 888 enum {
 889     kIOPMSystemCapabilityWillChange = 0x01,
 890     kIOPMSystemCapabilityDidChange  = 0x02
 891 };
 892
 893 enum {
 894     kIOPMSystemCapabilityCPU        = 0x01,
 895     kIOPMSystemCapabilityGraphics   = 0x02,
 896     kIOPMSystemCapabilityAudio      = 0x04,
 897     kIOPMSystemCapabilityNetwork    = 0x08
 898 };
 899
 900 #endif /* ! _IOKIT_IOPM_H */