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                = 0x80
 292 };
 293
 294  /* kIOPMAssertionsDriverKey
 295   * This kIOPMrootDomain key refers to a CFNumberRef property, containing
 296   * a bitfield describing the aggregate PM assertion levels.
 297   * Example: A value of 0 indicates that no driver has asserted anything.
 298   * Or, a value of <link>kIOPMDriverAssertionCPUBit</link>
 299   *   indicates that a driver (or drivers) have asserted a need fro CPU and video.
 300   */
 301 #define kIOPMAssertionsDriverKey            "DriverPMAssertions"
 302
 303  /* kIOPMAssertionsDriverKey
 304   * This kIOPMrootDomain key refers to a CFNumberRef property, containing
 305   * a bitfield describing the aggregate PM assertion levels.
 306   * Example: A value of 0 indicates that no driver has asserted anything.
 307   * Or, a value of <link>kIOPMDriverAssertionCPUBit</link>
 308   *   indicates that a driver (or drivers) have asserted a need fro CPU and video.
 309   */
 310 #define kIOPMAssertionsDriverDetailedKey    "DriverPMAssertionsDetailed"
 311
 312 /*******************************************************************************
 313  *
 314  * Kernel Driver assertion detailed dictionary keys
 315  *
 316  * Keys decode the Array & dictionary data structure under IOPMrootDomain property
 317  *  kIOPMAssertionsDriverKey.
 318  *
 319  */
 320 #define kIOPMDriverAssertionIDKey               "ID"
 321 #define kIOPMDriverAssertionCreatedTimeKey      "CreatedTime"
 322 #define kIOPMDriverAssertionModifiedTimeKey     "ModifiedTime"
 323 #define kIOPMDriverAssertionOwnerStringKey      "Owner"
 324 #define kIOPMDriverAssertionOwnerServiceKey     "ServicePtr"
 325 #define kIOPMDriverAssertionLevelKey            "Level"
 326 #define kIOPMDriverAssertionAssertedKey         "Assertions"
 327
 328 /*******************************************************************************
 329  *
 330  * Root Domain general interest messages
 331  *
 332  * Available by registering for interest type 'gIOGeneralInterest'
 333  * on IOPMrootDomain.
 334  *
 335  ******************************************************************************/
 336
 337 /* kIOPMMessageClamshellStateChange
 338  * Delivered as a general interest notification on the IOPMrootDomain
 339  * IOPMrootDomain sends this message when state of either AppleClamshellState
 340  * or AppleClamshellCausesSleep changes. If this clamshell change results in
 341  * a sleep, the sleep will initiate soon AFTER delivery of this message.
 342  * The state of both variables is encoded in a bitfield argument sent with
 343  * the message. Check bits 0 and 1 using kClamshellStateBit & kClamshellSleepBit
 344  */
 345 enum {
 346     kClamshellStateBit = (1 << 0),
 347     kClamshellSleepBit = (1 << 1)
 348 };
 349
 350 #define kIOPMMessageClamshellStateChange   \
 351                 iokit_family_msg(sub_iokit_powermanagement, 0x100)
 352
 353 /* kIOPMMessageFeatureChange
 354  * Delivered when the set of supported features ("Supported Features" dictionary
 355  * under IOPMrootDomain registry) changes in some way. Typically addition or
 356  * removal of a supported feature.
 357  * RootDomain passes no argument with this message.
 358  */
 359 #define kIOPMMessageFeatureChange           \
 360                 iokit_family_msg(sub_iokit_powermanagement, 0x110)
 361
 362 /* kIOPMMessageInflowDisableCancelled
 363  * The battery has drained completely to its "Fully Discharged" state.
 364  * If a user process has disabled battery inflow for battery
 365  * calibration, we forcibly re-enable Inflow at this point.
 366  * If inflow HAS been forcibly re-enabled, bit 0
 367  * (kInflowForciblyEnabledBit) will be set.
 368  */
 369 enum {
 370     kInflowForciblyEnabledBit = (1 << 0)
 371 };
 372
 373 /* kIOPMMessageInternalBatteryFullyDischarged
 374  * The battery has drained completely to its "Fully Discharged" state.
 375  */
 376 #define kIOPMMessageInternalBatteryFullyDischarged  \
 377                 iokit_family_msg(sub_iokit_powermanagement, 0x120)
 378
 379 /* kIOPMMessageSystemPowerEventOccurred
 380  * Some major system thermal property has changed, and interested clients may
 381  * modify their behavior.
 382  */
 383 #define kIOPMMessageSystemPowerEventOccurred  \
 384                 iokit_family_msg(sub_iokit_powermanagement, 0x130)
 385
 386 /* kIOPMMessageSleepWakeUUIDChange
 387  * Either a new SleepWakeUUID has been specified at the beginning of a sleep,
 388  * or we're removing the existing property upon completion of a wakeup.
 389  */
 390 #define kIOPMMessageSleepWakeUUIDChange  \
 391                 iokit_family_msg(sub_iokit_powermanagement, 0x140)
 392
 393 /* kIOPMMessageSleepWakeUUIDSet
 394  * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when
 395  * a new UUID has been specified.
 396  */
 397 #define kIOPMMessageSleepWakeUUIDSet                    ((void *)1)
 398
 399 /* kIOPMMessageSleepWakeUUIDCleared
 400  * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when
 401  * the current UUID has been removed.
 402  */
 403 #define kIOPMMessageSleepWakeUUIDCleared                ((void *)0)
 404
 405 /*! kIOPMMessageDriverAssertionsChanged
 406  *  Sent when kernel PM driver assertions have changed.
 407  */
 408 #define kIOPMMessageDriverAssertionsChanged  \
 409                 iokit_family_msg(sub_iokit_powermanagement, 0x150)
 410
 411 /*******************************************************************************
 412  *
 413  * Power commands issued to root domain
 414  * Use with IOPMrootDomain::receivePowerNotification()
 415  *
 416  * These commands are issued from system drivers only:
 417  *      ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily
 418  *
 419  * TODO: deprecate kIOPMAllowSleep and kIOPMPreventSleep
 420  ******************************************************************************/
 421 enum {
 422   kIOPMSleepNow                 = (1<<0),  // put machine to sleep now
 423   kIOPMAllowSleep               = (1<<1),  // allow idle sleep
 424   kIOPMPreventSleep             = (1<<2),  // do not allow idle sleep
 425   kIOPMPowerButton              = (1<<3),  // power button was pressed
 426   kIOPMClamshellClosed          = (1<<4),  // clamshell was closed
 427   kIOPMPowerEmergency           = (1<<5),  // battery dangerously low
 428   kIOPMDisableClamshell         = (1<<6),  // do not sleep on clamshell closure
 429   kIOPMEnableClamshell          = (1<<7),  // sleep on clamshell closure
 430   kIOPMProcessorSpeedChange     = (1<<8),  // change the processor speed
 431   kIOPMOverTemp                 = (1<<9),  // system dangerously hot
 432   kIOPMClamshellOpened          = (1<<10)  // clamshell was opened
 433 };
 434
 435
 436 /*******************************************************************************
 437  *
 438  * Power Management Return Codes
 439  *
 440  ******************************************************************************/
 441 enum {
 442     kIOPMNoErr                  = 0,
 443
 444     // Returned by driver's setPowerState(), powerStateWillChangeTo(),
 445     // powerStateDidChangeTo(), or acknowledgeSetPowerState() to
 446     // implicitly acknowledge power change upon function return.
 447     kIOPMAckImplied             = 0,
 448
 449     // Deprecated
 450     kIOPMWillAckLater           = 1,
 451
 452     // Returned by requestPowerDomainState() to indicate
 453     // unrecognized specification parameter.
 454     kIOPMBadSpecification       = 4,
 455
 456     // Returned by requestPowerDomainState() to indicate
 457     // no power state matches search specification.
 458     kIOPMNoSuchState            = 5,
 459
 460     // Deprecated
 461     kIOPMCannotRaisePower       = 6,
 462
 463     // Deprecated
 464     kIOPMParameterError         = 7,
 465
 466     // Returned when power management state is accessed
 467     // before driver has called PMinit().
 468     kIOPMNotYetInitialized      = 8,
 469
 470     // And the old constants; deprecated
 471     IOPMNoErr = kIOPMNoErr,
 472     IOPMAckImplied = kIOPMAckImplied,
 473     IOPMWillAckLater = kIOPMWillAckLater,
 474     IOPMBadSpecification = kIOPMBadSpecification,
 475     IOPMNoSuchState = kIOPMNoSuchState,
 476     IOPMCannotRaisePower = kIOPMCannotRaisePower,
 477     IOPMParameterError = kIOPMParameterError,
 478     IOPMNotYetInitialized = kIOPMNotYetInitialized
 479 };
 480
 481
 482 // IOPMPowerSource class descriptive strings
 483 // Power Source state is published as properties to the IORegistry under these
 484 // keys.
 485 #define kIOPMPSExternalConnectedKey                 "ExternalConnected"
 486 #define kIOPMPSExternalChargeCapableKey             "ExternalChargeCapable"
 487 #define kIOPMPSBatteryInstalledKey                  "BatteryInstalled"
 488 #define kIOPMPSIsChargingKey                        "IsCharging"
 489 #define kIOPMFullyChargedKey                        "FullyCharged"
 490 #define kIOPMPSAtWarnLevelKey                       "AtWarnLevel"
 491 #define kIOPMPSAtCriticalLevelKey                   "AtCriticalLevel"
 492 #define kIOPMPSCurrentCapacityKey                   "CurrentCapacity"
 493 #define kIOPMPSMaxCapacityKey                       "MaxCapacity"
 494 #define kIOPMPSDesignCapacityKey                    "DesignCapacity"
 495 #define kIOPMPSTimeRemainingKey                     "TimeRemaining"
 496 #define kIOPMPSAmperageKey                          "Amperage"
 497 #define kIOPMPSVoltageKey                           "Voltage"
 498 #define kIOPMPSCycleCountKey                        "CycleCount"
 499 #define kIOPMPSMaxErrKey                            "MaxErr"
 500 #define kIOPMPSAdapterInfoKey                       "AdapterInfo"
 501 #define kIOPMPSLocationKey                          "Location"
 502 #define kIOPMPSErrorConditionKey                    "ErrorCondition"
 503 #define kIOPMPSManufacturerKey                      "Manufacturer"
 504 #define kIOPMPSManufactureDateKey                   "ManufactureDate"
 505 #define kIOPMPSModelKey                             "Model"
 506 #define kIOPMPSSerialKey                            "Serial"
 507 #define kIOPMDeviceNameKey                          "DeviceName"
 508 #define kIOPMPSLegacyBatteryInfoKey                 "LegacyBatteryInfo"
 509 #define kIOPMPSBatteryHealthKey                     "BatteryHealth"
 510 #define kIOPMPSHealthConfidenceKey                  "HealthConfidence"
 511 #define kIOPMPSCapacityEstimatedKey                     "CapacityEstimated"
 512 #define kIOPMPSBatteryChargeStatusKey               "ChargeStatus"
 513 #define kIOPMPSBatteryTemperatureKey                "Temperature"
 514 #define kIOPMPSAdapterDetailsKey                    "AdapterDetails"
 515 #define kIOPMPSChargerConfigurationKey              "ChargerConfiguration"
 516
 517 // kIOPMPSBatteryChargeStatusKey may have one of the following values, or may have
 518 // no value. If kIOPMBatteryChargeStatusKey has a NULL value (or no value) associated with it
 519 // then charge is proceeding normally. If one of these battery charge status reasons is listed,
 520 // then the charge may have been interrupted.
 521 #define kIOPMBatteryChargeStatusTooHot              "HighTemperature"
 522 #define kIOPMBatteryChargeStatusTooCold             "LowTemperature"
 523 #define kIOPMBatteryChargeStatusTooHotOrCold        "HighOrLowTemperature"
 524 #define kIOPMBatteryChargeStatusGradient            "BatteryTemperatureGradient"
 525
 526 // Definitions for battery location, in case of multiple batteries.
 527 // A location of 0 is unspecified
 528 // Location is undefined for single battery systems
 529 enum {
 530     kIOPMPSLocationLeft = 1001,
 531     kIOPMPSLocationRight = 1002
 532 };
 533
 534 // Battery quality health types, specified by BatteryHealth and HealthConfidence
 535 // properties in an IOPMPowerSource battery kext.
 536 enum {
 537     kIOPMUndefinedValue = 0,
 538     kIOPMPoorValue      = 1,
 539     kIOPMFairValue      = 2,
 540     kIOPMGoodValue      = 3
 541 };
 542
 543 // Keys for kIOPMPSAdapterDetailsKey dictionary
 544 #define kIOPMPSAdapterDetailsIDKey                  "AdapterID"
 545 #define kIOPMPSAdapterDetailsWattsKey               "Watts"
 546 #define kIOPMPSAdapterDetailsRevisionKey            "AdapterRevision"
 547 #define kIOPMPSAdapterDetailsSerialNumberKey        "SerialNumber"
 548 #define kIOPMPSAdapterDetailsFamilyKey              "FamilyCode"
 549 #define kIOPMPSAdapterDetailsAmperageKey            "Amperage"
 550 #define kIOPMPSAdapterDetailsDescriptionKey         "Description"
 551 #define kIOPMPSAdapterDetailsPMUConfigurationKey    "PMUConfiguration"
 552
 553 // Battery's time remaining estimate is invalid this long (seconds) after a wake
 554 #define kIOPMPSInvalidWakeSecondsKey           "BatteryInvalidWakeSeconds"
 555
 556 // Battery must wait this long (seconds) after being completely charged before
 557 // the battery is settled.
 558 #define kIOPMPSPostChargeWaitSecondsKey        "PostChargeWaitSeconds"
 559
 560 // Battery must wait this long (seconds) after being completely discharged
 561 // before the battery is settled.
 562 #define kIOPMPSPostDishargeWaitSecondsKey      "PostDischargeWaitSeconds"
 563
 564
 565 /* CPU Power Management status keys
 566  * Pass as arguments to IOPMrootDomain::systemPowerEventOccurred
 567  * Or as arguments to IOPMSystemPowerEventOccurred()
 568  * Or to decode the dictionary obtained from IOPMCopyCPUPowerStatus()
 569  * These keys reflect restrictions placed on the CPU by the system
 570  * to bring the CPU's power consumption within allowable thermal and
 571  * power constraints.
 572  */
 573
 574
 575 /* kIOPMGraphicsPowerLimitsKey
 576  *   The key representing the dictionary of graphics power limits.
 577  *   The dictionary contains the other kIOPMCPUPower keys & their associated
 578  *   values (e.g. Speed limit, Processor Count, and Schedule limits).
 579  */
 580 #define kIOPMGraphicsPowerLimitsKey                     "Graphics_Power_Limits"
 581
 582 /* kIOPMGraphicsPowerLimitPerformanceKey
 583  *   The key representing the percent of overall performance made available
 584  *   by the graphics chip as a percentage (integer 0 - 100).
 585  */
 586 #define kIOPMGraphicsPowerLimitPerformanceKey           "Graphics_Power_Performance"
 587
 588
 589
 590 /* kIOPMCPUPowerLimitsKey
 591  *   The key representing the dictionary of CPU Power Limits.
 592  *   The dictionary contains the other kIOPMCPUPower keys & their associated
 593  *   values (e.g. Speed limit, Processor Count, and Schedule limits).
 594  */
 595 #define kIOPMCPUPowerLimitsKey                          "CPU_Power_Limits"
 596
 597 /* kIOPMCPUPowerLimitProcessorSpeedKey defines the speed & voltage limits placed
 598  *   on the CPU.
 599  *   Represented as a percentage (0-100) of maximum CPU speed.
 600  */
 601 #define kIOPMCPUPowerLimitProcessorSpeedKey             "CPU_Speed_Limit"
 602
 603 /* kIOPMCPUPowerLimitProcessorCountKey reflects how many, if any, CPUs have been
 604  *   taken offline. Represented as an integer number of CPUs (0 - Max CPUs).
 605  */
 606 #define kIOPMCPUPowerLimitProcessorCountKey             "CPU_Available_CPUs"
 607
 608 /* kIOPMCPUPowerLimitSchedulerTimeKey represents the percentage (0-100) of CPU time
 609  *   available. 100% at normal operation. The OS may limit this time for a percentage
 610  *   less than 100%.
 611  */
 612 #define kIOPMCPUPowerLimitSchedulerTimeKey              "CPU_Scheduler_Limit"
 613
 614
 615 /* Thermal Level Warning Key
 616  * Indicates the thermal constraints placed on the system. This value may
 617  * cause clients to action to consume fewer system resources.
 618  * The value associated with this warning is defined by the platform.
 619  */
 620 #define kIOPMThermalLevelWarningKey                     "Thermal_Level_Warning"
 621
 622 /* Thermal Warning Level values
 623  *      kIOPMThermalWarningLevelNormal - under normal operating conditions
 624  *      kIOPMThermalWarningLevelDanger - thermal pressure may cause system slowdown
 625  *      kIOPMThermalWarningLevelCrisis - thermal conditions may cause imminent shutdown
 626  *
 627  * The platform may define additional thermal levels if necessary.
 628  */
 629 enum {
 630   kIOPMThermalWarningLevelNormal    = 0,
 631   kIOPMThermalWarningLevelDanger    = 5,
 632   kIOPMThermalWarningLevelCrisis    = 10
 633 };
 634
 635
 636 // PM Settings Controller setting types
 637 // Settings types used primarily with:
 638 //      IOPMrootDomain::registerPMSettingController
 639 // The values are identical to the similarly named keys for use in user space
 640 // PM settings work. Those keys are defined in IOPMLibPrivate.h.
 641 #define kIOPMSettingWakeOnRingKey                   "Wake On Modem Ring"
 642 #define kIOPMSettingRestartOnPowerLossKey           "Automatic Restart On Power Loss"
 643 #define kIOPMSettingWakeOnACChangeKey               "Wake On AC Change"
 644 #define kIOPMSettingSleepOnPowerButtonKey           "Sleep On Power Button"
 645 #define kIOPMSettingWakeOnClamshellKey              "Wake On Clamshell Open"
 646 #define kIOPMSettingReduceBrightnessKey             "ReduceBrightness"
 647 #define kIOPMSettingDisplaySleepUsesDimKey          "Display Sleep Uses Dim"
 648 #define kIOPMSettingTimeZoneOffsetKey               "TimeZoneOffsetSeconds"
 649 #define kIOPMSettingMobileMotionModuleKey           "MobileMotionModule"
 650 #define kIOPMSettingGraphicsSwitchKey               "GPUSwitch"
 651
 652 // Setting controlling drivers can register to receive scheduled wake data
 653 // Either in "CF seconds" type, or structured calendar data in a formatted
 654 // IOPMCalendarStruct defined below.
 655 #define kIOPMSettingAutoWakeSecondsKey              "wake"
 656 #define kIOPMSettingAutoWakeCalendarKey             "WakeByCalendarDate"
 657 #define kIOPMSettingAutoPowerSecondsKey             "poweron"
 658 #define kIOPMSettingAutoPowerCalendarKey            "PowerByCalendarDate"
 659
 660 // Debug seconds auto wake
 661 // Used by sleep cycling debug tools
 662 #define kIOPMSettingDebugWakeRelativeKey            "WakeRelativeToSleep"
 663 #define kIOPMSettingDebugPowerRelativeKey           "PowerRelativeToShutdown"
 664
 665 // Maintenance wake calendar.
 666 #define kIOPMSettingMaintenanceWakeCalendarKey      "MaintenanceWakeCalendarDate"
 667
 668 struct IOPMCalendarStruct {
 669     UInt32      year;
 670     UInt8       month;
 671     UInt8       day;
 672     UInt8       hour;
 673     UInt8       minute;
 674     UInt8       second;
 675 };
 676 typedef struct IOPMCalendarStruct IOPMCalendarStruct;
 677
 678 // SetAggressiveness types
 679 enum {
 680     kPMGeneralAggressiveness = 0,
 681     kPMMinutesToDim,
 682     kPMMinutesToSpinDown,
 683     kPMMinutesToSleep,
 684     kPMEthernetWakeOnLANSettings,
 685     kPMSetProcessorSpeed,
 686     kPMPowerSource,
 687     kPMMotionSensor,
 688     kPMLastAggressivenessType
 689 };
 690 #define kMaxType (kPMLastAggressivenessType-1)
 691
 692 // SetAggressiveness values for the kPMPowerSource aggressiveness type
 693 enum {
 694     kIOPMInternalPower = 1,
 695     kIOPMExternalPower
 696 };
 697
 698 #define kIOREMSleepEnabledKey               "REMSleepEnabled"
 699
 700 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo
 701 #define kIOBatteryInfoKey                   "IOBatteryInfo"
 702 #define kIOBatteryCurrentChargeKey          "Current"
 703 #define kIOBatteryCapacityKey               "Capacity"
 704 #define kIOBatteryFlagsKey                  "Flags"
 705 #define kIOBatteryVoltageKey                "Voltage"
 706 #define kIOBatteryAmperageKey               "Amperage"
 707 #define kIOBatteryCycleCountKey             "Cycle Count"
 708
 709 enum {
 710     kIOBatteryInstalled         = (1 << 2),
 711     kIOBatteryCharge            = (1 << 1),
 712     kIOBatteryChargerConnect    = (1 << 0)
 713 };
 714
 715 // Private power management message indicating battery data has changed
 716 // Indicates new data resides in the IORegistry
 717 #define kIOPMMessageBatteryStatusHasChanged         iokit_family_msg(sub_iokit_pmu, 0x100)
 718
 719 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU
 720 // through newer user space IOPMSchedulePowerEvent API
 721 #define kIOPMUMessageLegacyAutoWake                 iokit_family_msg(sub_iokit_pmu, 0x200)
 722 #define kIOPMUMessageLegacyAutoPower                iokit_family_msg(sub_iokit_pmu, 0x210)
 723
 724 // For use with IOPMPowerSource bFlags
 725 #define IOPM_POWER_SOURCE_REV   2
 726 enum {
 727   kIOPMACInstalled      = kIOBatteryChargerConnect,
 728   kIOPMBatteryCharging  = kIOBatteryCharge,
 729   kIOPMBatteryInstalled = kIOBatteryInstalled,
 730   kIOPMUPSInstalled     = (1<<3),
 731   kIOPMBatteryAtWarn    = (1<<4),
 732   kIOPMBatteryDepleted  = (1<<5),
 733   kIOPMACnoChargeCapability = (1<<6),     // AC adapter cannot charge battery
 734   kIOPMRawLowBattery    = (1<<7),         // used only by  Platform Expert
 735   kIOPMForceLowSpeed    = (1<<8),         // set by Platfm Expert, chk'd by Pwr Plugin
 736   kIOPMClosedClamshell  = (1<<9),         // set by PMU - reflects state of the clamshell
 737   kIOPMClamshellStateOnWake = (1<<10)     // used only by Platform Expert
 738 };
 739
 740 // **********************************************
 741 // Internal power management data structures
 742 // **********************************************
 743
 744 #if KERNEL && __cplusplus
 745 class IOService;
 746
 747 enum {
 748     kIOPowerEmergencyLevel = 1000
 749 };
 750
 751 enum {
 752     kIOPMSubclassPolicy,
 753     kIOPMSuperclassPolicy1
 754 };
 755
 756 struct stateChangeNote {
 757     IOPMPowerFlags    stateFlags;
 758     unsigned long    stateNum;
 759     void *         powerRef;
 760 };
 761 typedef struct stateChangeNote stateChangeNote;
 762
 763 struct IOPowerStateChangeNotification {
 764     void *        powerRef;
 765     unsigned long    returnValue;
 766     unsigned long    stateNumber;
 767     IOPMPowerFlags    stateFlags;
 768 };
 769 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification;
 770 typedef IOPowerStateChangeNotification sleepWakeNote;
 771 #endif /* KERNEL && __cplusplus */
 772
 773 /*! @struct IOPMSystemCapabilityChangeParameters
 774     @abstract A structure describing a system capability change.
 775     @discussion A system capability change is a system level transition from a set
 776         of system capabilities to a new set of system capabilities. Power management
 777         sends a <code>kIOMessageSystemCapabilityChange</code> message and provides
 778         this structure as the message data (by reference) to
 779         <code>gIOPriorityPowerStateInterest</code> clients when system capability
 780         changes.
 781     @field notifyRef An identifier for this message notification. Clients with pending
 782         I/O can signal completion by calling <code>allowPowerChange()</code> with this
 783         value as the argument. Clients that are able to process the notification
 784         synchronously should ignore this field.
 785     @field maxWaitForReply A return value to the caller indicating the maximum time in
 786         microseconds to wait for the <code>allowPowerChange()</code> call. The default
 787         value is zero, which indicates the client processing has finished, and power
 788         management should not wait for an <code>allowPowerChange()</code> call.
 789     @field changeFlags Flags will be set to indicate whether the notification precedes
 790         the capability change (<code>kIOPMSystemCapabilityWillChange</code>), or after
 791         the capability change has occurred (<code>kIOPMSystemCapabilityDidChange</code>).
 792     @field __reserved1 Set to zero.
 793     @field fromCapabilities The system capabilities at the start of the transition.
 794     @field toCapabilities The system capabilities at the end of the transition.
 795     @field __reserved2 Set to zero.
 796  */
 797 struct IOPMSystemCapabilityChangeParameters {
 798     uint32_t    notifyRef;
 799     uint32_t    maxWaitForReply;
 800     uint32_t    changeFlags;
 801     uint32_t    __reserved1;
 802     uint32_t    fromCapabilities;
 803     uint32_t    toCapabilities;
 804     uint32_t    __reserved2[4];
 805 };
 806
 807 /*! @enum IOPMSystemCapabilityChangeFlags
 808     @constant kIOPMSystemCapabilityWillChange Indicates the system capability will change.
 809     @constant kIOPMSystemCapabilityDidChange Indicates the system capability has changed.
 810 */
 811 enum {
 812     kIOPMSystemCapabilityWillChange = 0x01,
 813     kIOPMSystemCapabilityDidChange  = 0x02
 814 };
 815
 816 enum {
 817     kIOPMSystemCapabilityCPU        = 0x01,
 818     kIOPMSystemCapabilityGraphics   = 0x02,
 819     kIOPMSystemCapabilityAudio      = 0x04,
 820     kIOPMSystemCapabilityNetwork    = 0x08
 821 };
 822
 823 #endif /* ! _IOKIT_IOPM_H */