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