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 #ifdef __ppc__
  36 #include <IOKit/pwr_mgt/IOPMDeprecated.h>
  37 #endif
  38
  39
  40
  41 enum {
  42     kIOPMMaxPowerStates = 10,
  43     IOPMMaxPowerStates = kIOPMMaxPowerStates
  44 };
  45
  46 typedef unsigned long IOPMPowerFlags;
  47 enum {
  48     // The following  bits are used in the input and output power fields.
  49     kIOPMClockNormal                = 0x0004,
  50     kIOPMClockRunning               = 0x0008,
  51     // Reserved - Used only between root and root parent.
  52     kIOPMAuxPowerOn                 = 0x0020,
  53     // Reserved - kIOPMPagingAvailable used only by now-defunct paging plexus
  54     kIOPMPagingAvailable            = 0x0020,
  55     kIOPMPassThrough                = 0x0100,
  56     kIOPMDoze                       = 0x0400,
  57     // Obsolete - use kIOPMDoze instead of kIOPMSoftSleep
  58     kIOPMSoftSleep                  = 0x0400,
  59     kIOPMSleep                      = 0x0001,
  60     kIOPMRestart                    = 0x0080,
  61
  62     // The following bits are used in the capabilites field and the power fields
  63     kIOPMPowerOn                    = 0x0002,
  64     kIOPMPreventSystemSleep         = 0x0010,
  65     kIOPMPreventIdleSleep           = 0x0040,
  66
  67     // The following  bits are used in the capabilites field only.
  68     // Used between a driver and its policy-maker
  69     kIOPMNotAttainable              = 0x0001,
  70     // Used internally in a power domain parent
  71     kIOPMChildClamp                 = 0x0080,
  72     // Used internally in a power domain parent
  73     kIOPMChildClamp2                = 0x0200,
  74     // Marks device as usable in this state
  75     kIOPMDeviceUsable               = 0x8000,
  76     // Device runs at max performance in this state
  77     kIOPMMaxPerformance             = 0x4000,
  78     kIOPMContextRetained            = 0x2000,
  79     kIOPMConfigRetained             = 0x1000,
  80     // Device is capable of system sleep in this state
  81     kIOPMSleepCapability            = 0x0004,
  82     kIOPMRestartCapability          = 0x0080,
  83
  84     // Reserved - Error code. (this is an error return rather than a bit)
  85     kIOPMNotPowerManaged            = 0x0800,
  86     // Therefore this bit safely overloads it
  87     kIOPMStaticPowerValid           = 0x0800,
  88
  89     kIOPMCapabilitiesMask =     kIOPMPowerOn | kIOPMDeviceUsable |
  90                                 kIOPMMaxPerformance | kIOPMContextRetained |
  91                                 kIOPMConfigRetained | kIOPMSleepCapability |
  92                                 kIOPMRestartCapability
  93 };
  94
  95
  96 enum {
  97     IOPMNotAttainable           = kIOPMNotAttainable,
  98     IOPMPowerOn                 = kIOPMPowerOn,
  99     IOPMClockNormal             = kIOPMClockNormal,
 100     IOPMClockRunning            = kIOPMClockRunning,
 101     IOPMAuxPowerOn              = kIOPMAuxPowerOn,
 102     IOPMDeviceUsable            = kIOPMDeviceUsable,
 103     IOPMMaxPerformance          = kIOPMMaxPerformance,
 104     IOPMContextRetained         = kIOPMContextRetained,
 105     IOPMConfigRetained          = kIOPMConfigRetained,
 106     IOPMNotPowerManaged         = kIOPMNotPowerManaged,
 107     IOPMPagingAvailable         = kIOPMPagingAvailable,
 108     IOPMSoftSleep               = kIOPMSoftSleep
 109 };
 110
 111
 112 enum {
 113     kIOPMNextHigherState        = 1,
 114     kIOPMHighestState           = 2,
 115     kIOPMNextLowerState         = 3,
 116     kIOPMLowestState            = 4
 117 };
 118
 119 enum {
 120     IOPMNextHigherState         = kIOPMNextHigherState,
 121     IOPMHighestState            = kIOPMHighestState,
 122     IOPMNextLowerState          = kIOPMNextLowerState,
 123     IOPMLowestState             = kIOPMLowestState
 124 };
 125
 126 // Internal commands used by power managment command queue
 127 enum {
 128     kIOPMBroadcastAggressiveness = 1,
 129     kIOPMUnidleDevice
 130 };
 131
 132 // Power consumption unknown value
 133 enum {
 134     kIOPMUnknown = 0xFFFF
 135 };
 136
 137 /*******************************************************************************
 138  *
 139  * Root Domain property keys of interest
 140  *
 141  ******************************************************************************/
 142
 143 /* AppleClamshellState
 144  * reflects the state of the clamshell (lid) on a portable.
 145  * It has a boolean value.
 146  *  true        == clamshell is closed
 147  *  false       == clamshell is open
 148  *  not present == no clamshell on this hardware
 149  */
 150 #define kAppleClamshellStateKey             "AppleClamshellState"
 151
 152 /* AppleClamshellCausesSleep
 153  * reflects the clamshell close behavior on a portable.
 154  * It has a boolean value.
 155  *  true        == system will sleep when clamshell is closed
 156  *  false       == system will not sleep on clamshell close
 157  *                  (typically external display mode)
 158  *  not present == no clamshell on this hardware
 159  */
 160 #define kAppleClamshellCausesSleepKey       "AppleClamshellCausesSleep"
 161
 162 /*******************************************************************************
 163  *
 164  * Root Domain general interest messages
 165  *
 166  ******************************************************************************/
 167
 168 /* kIOPMMessageClamshellStateChange
 169  * Delivered as a general interest notification on the IOPMrootDomain
 170  * IOPMrootDomain sends this message when state of either AppleClamshellState
 171  * or AppleClamshellCausesSleep changes. If this clamshell change results in
 172  * a sleep, the sleep will initiate soon AFTER delivery of this message.
 173  * The state of both variables is encoded in a bitfield argument sent with
 174  * the message. Check bits 0 and 1 using kClamshellStateBit & kClamshellSleepBit
 175  */
 176 enum {
 177     kClamshellStateBit = (1 << 0),
 178     kClamshellSleepBit = (1 << 1)
 179 };
 180
 181 #define kIOPMMessageClamshellStateChange   \
 182                 iokit_family_msg(sub_iokit_powermanagement, 0x100)
 183
 184 /* kIOPMMessageFeatureChange
 185  * Delivered when the set of supported features ("Supported Features" dictionary
 186  * under IOPMrootDomain registry) changes in some way. Typically addition or
 187  * removal of a supported feature.
 188  * RootDomain passes no argument with this message.
 189  */
 190 #define kIOPMMessageFeatureChange           \
 191                 iokit_family_msg(sub_iokit_powermanagement, 0x110)
 192
 193 /* kIOPMMessageInflowDisableCancelled
 194  * The battery has drained completely to its "Fully Discharged" state.
 195  * If a user process has disabled battery inflow for battery
 196  * calibration, we forcibly re-enable Inflow at this point.
 197  * If inflow HAS been forcibly re-enabled, bit 0
 198  * (kInflowForciblyEnabledBit) will be set.
 199  */
 200 enum {
 201     kInflowForciblyEnabledBit = (1 << 0)
 202 };
 203
 204 #define kIOPMMessageInternalBatteryFullyDischarged  \
 205                 iokit_family_msg(sub_iokit_powermanagement, 0x120)
 206
 207
 208 /*******************************************************************************
 209  *
 210  * Power commands issued to root domain
 211  *
 212  * These commands are issued from system drivers only:
 213  *      ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily
 214  *
 215  ******************************************************************************/
 216 enum {
 217   kIOPMSleepNow                 = (1<<0),  // put machine to sleep now
 218   kIOPMAllowSleep               = (1<<1),  // allow idle sleep
 219   kIOPMPreventSleep             = (1<<2),  // do not allow idle sleep
 220   kIOPMPowerButton              = (1<<3),  // power button was pressed
 221   kIOPMClamshellClosed          = (1<<4),  // clamshell was closed
 222   kIOPMPowerEmergency           = (1<<5),  // battery dangerously low
 223   kIOPMDisableClamshell         = (1<<6),  // do not sleep on clamshell closure
 224   kIOPMEnableClamshell          = (1<<7),  // sleep on clamshell closure
 225   kIOPMProcessorSpeedChange     = (1<<8),  // change the processor speed
 226   kIOPMOverTemp                 = (1<<9),  // system dangerously hot
 227   kIOPMClamshellOpened          = (1<<10)  // clamshell was opened
 228 };
 229
 230 /*******************************************************************************
 231  *
 232  * Power Management Return Codes
 233  *
 234  ******************************************************************************/
 235 enum {
 236     kIOPMNoErr                  = 0,
 237     // Returned by powerStateWillChange and powerStateDidChange:
 238     // Immediate acknowledgement of power state change
 239     kIOPMAckImplied             = 0,
 240     // Acknowledgement of power state change will come later
 241     kIOPMWillAckLater           = 1,
 242
 243     // Returned by requestDomainState:
 244     // Unrecognized specification parameter
 245     kIOPMBadSpecification       = 4,
 246     // No power state matches search specification
 247     kIOPMNoSuchState            = 5,
 248
 249     // Device cannot change its power for some reason
 250     kIOPMCannotRaisePower       = 6,
 251
 252   // Returned by changeStateTo:
 253     // Requested state doesn't exist
 254     kIOPMParameterError         = 7,
 255     // Device not yet fully hooked into power management
 256     kIOPMNotYetInitialized      = 8,
 257
 258     // And the old constants; deprecated
 259     IOPMNoErr = kIOPMNoErr,
 260     IOPMAckImplied = kIOPMAckImplied,
 261     IOPMWillAckLater = kIOPMWillAckLater,
 262     IOPMBadSpecification = kIOPMBadSpecification,
 263     IOPMNoSuchState = kIOPMNoSuchState,
 264     IOPMCannotRaisePower = kIOPMCannotRaisePower,
 265     IOPMParameterError = kIOPMParameterError,
 266     IOPMNotYetInitialized = kIOPMNotYetInitialized
 267 };
 268
 269
 270 // IOPMPowerSource class descriptive strings
 271 // Power Source state is published as properties to the IORegistry under these
 272 // keys.
 273 #define kIOPMPSExternalConnectedKey                 "ExternalConnected"
 274 #define kIOPMPSExternalChargeCapableKey             "ExternalChargeCapable"
 275 #define kIOPMPSBatteryInstalledKey                  "BatteryInstalled"
 276 #define kIOPMPSIsChargingKey                        "IsCharging"
 277 #define kIOPMFullyChargedKey                        "FullyCharged"
 278 #define kIOPMPSAtWarnLevelKey                       "AtWarnLevel"
 279 #define kIOPMPSAtCriticalLevelKey                   "AtCriticalLevel"
 280 #define kIOPMPSCurrentCapacityKey                   "CurrentCapacity"
 281 #define kIOPMPSMaxCapacityKey                       "MaxCapacity"
 282 #define kIOPMPSDesignCapacityKey                    "DesignCapacity"
 283 #define kIOPMPSTimeRemainingKey                     "TimeRemaining"
 284 #define kIOPMPSAmperageKey                          "Amperage"
 285 #define kIOPMPSVoltageKey                           "Voltage"
 286 #define kIOPMPSCycleCountKey                        "CycleCount"
 287 #define kIOPMPSMaxErrKey                            "MaxErr"
 288 #define kIOPMPSAdapterInfoKey                       "AdapterInfo"
 289 #define kIOPMPSLocationKey                          "Location"
 290 #define kIOPMPSErrorConditionKey                    "ErrorCondition"
 291 #define kIOPMPSManufacturerKey                      "Manufacturer"
 292 #define kIOPMPSManufactureDateKey                   "ManufactureDate"
 293 #define kIOPMPSModelKey                             "Model"
 294 #define kIOPMPSSerialKey                            "Serial"
 295 #define kIOPMDeviceNameKey                          "DeviceName"
 296 #define kIOPMPSLegacyBatteryInfoKey                 "LegacyBatteryInfo"
 297 #define kIOPMPSBatteryHealthKey                     "BatteryHealth"
 298 #define kIOPMPSHealthConfidenceKey                  "HealthConfidence"
 299
 300 // Definitions for battery location, in case of multiple batteries.
 301 // A location of 0 is unspecified
 302 // Location is undefined for single battery systems
 303 enum {
 304     kIOPMPSLocationLeft = 1001,
 305     kIOPMPSLocationRight = 1002
 306 };
 307
 308 // Battery quality health types, specified by BatteryHealth and HealthConfidence
 309 // properties in an IOPMPowerSource battery kext.
 310 enum {
 311     kIOPMUndefinedValue = 0,
 312     kIOPMPoorValue      = 1,
 313     kIOPMFairValue      = 2,
 314     kIOPMGoodValue      = 3
 315 };
 316
 317 // Battery's time remaining estimate is invalid this long (seconds) after a wake
 318 #define kIOPMPSInvalidWakeSecondsKey           "BatteryInvalidWakeSeconds"
 319
 320 // Battery must wait this long (seconds) after being completely charged before
 321 // the battery is settled.
 322 #define kIOPMPSPostChargeWaitSecondsKey        "PostChargeWaitSeconds"
 323
 324 // Battery must wait this long (seconds) after being completely discharged
 325 // before the battery is settled.
 326 #define kIOPMPSPostDishargeWaitSecondsKey      "PostDischargeWaitSeconds"
 327
 328
 329
 330 // PM Settings Controller setting types
 331 // Settings types used primarily with:
 332 //      IOPMrootDomain::registerPMSettingController
 333 // The values are identical to the similarly named keys for use in user space
 334 // PM settings work. Those keys are defined in IOPMLibPrivate.h.
 335 #define kIOPMSettingWakeOnRingKey                   "Wake On Modem Ring"
 336 #define kIOPMSettingRestartOnPowerLossKey           "Automatic Restart On Power Loss"
 337 #define kIOPMSettingWakeOnACChangeKey               "Wake On AC Change"
 338 #define kIOPMSettingSleepOnPowerButtonKey           "Sleep On Power Button"
 339 #define kIOPMSettingWakeOnClamshellKey              "Wake On Clamshell Open"
 340 #define kIOPMSettingReduceBrightnessKey             "ReduceBrightness"
 341 #define kIOPMSettingDisplaySleepUsesDimKey          "Display Sleep Uses Dim"
 342 #define kIOPMSettingTimeZoneOffsetKey               "TimeZoneOffsetSeconds"
 343 #define kIOPMSettingMobileMotionModuleKey           "MobileMotionModule"
 344
 345 // Setting controlling drivers can register to receive scheduled wake data
 346 // Either in "CF seconds" type, or structured calendar data in a formatted
 347 // IOPMCalendarStruct defined below.
 348 #define kIOPMSettingAutoWakeSecondsKey              "wake"
 349 #define kIOPMSettingAutoWakeCalendarKey             "WakeByCalendarDate"
 350 #define kIOPMSettingAutoPowerSecondsKey             "poweron"
 351 #define kIOPMSettingAutoPowerCalendarKey            "PowerByCalendarDate"
 352
 353 // Debug seconds auto wake
 354 // Used by sleep cycling debug tools
 355 #define kIOPMSettingDebugWakeRelativeKey            "WakeRelativeToSleep"
 356 #define kIOPMSettingDebugPowerRelativeKey           "PowerRelativeToShutdown"
 357
 358 struct IOPMCalendarStruct {
 359     UInt32      year;
 360     UInt8       month;
 361     UInt8       day;
 362     UInt8       hour;
 363     UInt8       minute;
 364     UInt8       second;
 365 };
 366 typedef struct IOPMCalendarStruct IOPMCalendarStruct;
 367
 368 // SetAggressiveness types
 369 enum {
 370     kPMGeneralAggressiveness = 0,
 371     kPMMinutesToDim,
 372     kPMMinutesToSpinDown,
 373     kPMMinutesToSleep,
 374     kPMEthernetWakeOnLANSettings,
 375     kPMSetProcessorSpeed,
 376     kPMPowerSource,
 377     kPMMotionSensor,
 378     kPMLastAggressivenessType
 379 };
 380 #define kMaxType (kPMLastAggressivenessType-1)
 381
 382 // SetAggressiveness values for the kPMPowerSource aggressiveness type
 383 enum {
 384     kIOPMInternalPower = 1,
 385     kIOPMExternalPower
 386 };
 387
 388 #define kIOREMSleepEnabledKey               "REMSleepEnabled"
 389
 390 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo
 391 #define kIOBatteryInfoKey                   "IOBatteryInfo"
 392 #define kIOBatteryCurrentChargeKey          "Current"
 393 #define kIOBatteryCapacityKey               "Capacity"
 394 #define kIOBatteryFlagsKey                  "Flags"
 395 #define kIOBatteryVoltageKey                "Voltage"
 396 #define kIOBatteryAmperageKey               "Amperage"
 397 #define kIOBatteryCycleCountKey             "Cycle Count"
 398
 399 enum {
 400     kIOBatteryInstalled         = (1 << 2),
 401     kIOBatteryCharge            = (1 << 1),
 402     kIOBatteryChargerConnect    = (1 << 0)
 403 };
 404
 405
 406 // Private power management message indicating battery data has changed
 407 // Indicates new data resides in the IORegistry
 408 #define kIOPMMessageBatteryStatusHasChanged         iokit_family_msg(sub_iokit_pmu, 0x100)
 409
 410 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU
 411 // through newer user space IOPMSchedulePowerEvent API
 412 #define kIOPMUMessageLegacyAutoWake                 iokit_family_msg(sub_iokit_pmu, 0x200)
 413 #define kIOPMUMessageLegacyAutoPower                iokit_family_msg(sub_iokit_pmu, 0x210)
 414
 415 // For use with IOPMPowerSource bFlags
 416 #define IOPM_POWER_SOURCE_REV   2
 417 enum {
 418   kIOPMACInstalled      = kIOBatteryChargerConnect,
 419   kIOPMBatteryCharging  = kIOBatteryCharge,
 420   kIOPMBatteryInstalled = kIOBatteryInstalled,
 421   kIOPMUPSInstalled     = (1<<3),
 422   kIOPMBatteryAtWarn    = (1<<4),
 423   kIOPMBatteryDepleted  = (1<<5),
 424   kIOPMACnoChargeCapability = (1<<6),     // AC adapter cannot charge battery
 425   kIOPMRawLowBattery    = (1<<7),         // used only by  Platform Expert
 426   kIOPMForceLowSpeed    = (1<<8),         // set by Platfm Expert, chk'd by Pwr Plugin
 427   kIOPMClosedClamshell  = (1<<9),         // set by PMU - reflects state of the clamshell
 428   kIOPMClamshellStateOnWake = (1<<10)     // used only by Platform Expert
 429 };
 430
 431
 432 // **********************************************
 433 // Internal power management data structures
 434 // **********************************************
 435
 436 #if KERNEL && __cplusplus
 437 class IOService;
 438
 439 enum {
 440     kIOPowerEmergencyLevel = 1000
 441 };
 442
 443 enum {
 444     kIOPMSubclassPolicy,
 445     kIOPMSuperclassPolicy1
 446 };
 447
 448 struct stateChangeNote{
 449     IOPMPowerFlags    stateFlags;
 450     unsigned long    stateNum;
 451     void *         powerRef;
 452 };
 453 typedef struct stateChangeNote stateChangeNote;
 454
 455 struct IOPowerStateChangeNotification {
 456     void *        powerRef;
 457     unsigned long    returnValue;
 458     unsigned long    stateNumber;
 459     IOPMPowerFlags    stateFlags;
 460 };
 461 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification;
 462 typedef IOPowerStateChangeNotification sleepWakeNote;
 463
 464 extern void IOPMRegisterDevice(const char *, IOService *);
 465 #endif /* KERNEL && __cplusplus */
 466
 467 #endif /* ! _IOKIT_IOPM_H */
 468