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