iokit/IOKit/pwr_mgt/IOPM.h

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