iokit/IOKit/pwr_mgt/IOPM.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 #ifndef _IOKIT_IOPM_H
  26 #define _IOKIT_IOPM_H
  27
  28 #define IOPMMaxPowerStates 10
  29
  30 typedef unsigned long IOPMPowerFlags;
  31 enum {
  32                         // following  bits are used in the input and output power fields
  33     kIOPMClockNormal            = 0x0004,
  34     kIOPMClockRunning           = 0x0008,
  35     kIOPMAuxPowerOn             = 0x0020,       // used only between root and root parent
  36     kIOPMPagingAvailable        = 0x0020,       // used only between paging plexus and its children
  37     kIOPMPassThrough            = 0x0100,
  38     kIOPMDoze                   = 0x0400,
  39     kIOPMSoftSleep              = 0x0400,       // old usage, replaced by kIOPMDoze
  40     kIOPMSleep                  = 0x0001,
  41     kIOPMRestart                = 0x0080,
  42                         // following  bits are used in the capabilites field and the power fields
  43     kIOPMPowerOn                = 0x0002,
  44     kIOPMPreventSystemSleep     = 0x0010,
  45     kIOPMPreventIdleSleep       = 0x0040,
  46                         // following  bits are used in the capabilites field
  47     kIOPMNotAttainable          = 0x0001,       // used between a driver and its policy-maker
  48     kIOPMChildClamp             = 0x0080,       // used internally in a power domain parent
  49     kIOPMChildClamp2            = 0x0200,       // used internally in a power domain parent
  50     kIOPMDeviceUsable           = 0x8000,
  51     kIOPMMaxPerformance         = 0x4000,
  52     kIOPMContextRetained        = 0x2000,
  53     kIOPMConfigRetained         = 0x1000,
  54     kIOPMSleepCapability        = 0x0004,
  55     kIOPMRestartCapability      = 0x0080,
  56     kIOPMNotPowerManaged        = 0x0800,       // this is an error return rather than a bit
  57     kIOPMStaticPowerValid       = 0x0800,       // therefore this bit safely overloads it
  58
  59     kIOPMCapabilitiesMask =     kIOPMPowerOn | kIOPMDeviceUsable | kIOPMMaxPerformance |
  60                                 kIOPMContextRetained | kIOPMConfigRetained | kIOPMSleepCapability |
  61                                 kIOPMRestartCapability
  62 };
  63
  64
  65 enum {
  66     IOPMNotAttainable   = kIOPMNotAttainable,
  67     IOPMPowerOn         = kIOPMPowerOn,
  68     IOPMClockNormal     = kIOPMClockNormal,
  69     IOPMClockRunning    = kIOPMClockRunning,
  70     IOPMAuxPowerOn      = kIOPMAuxPowerOn,
  71     IOPMDeviceUsable    = kIOPMDeviceUsable,
  72     IOPMMaxPerformance  = kIOPMMaxPerformance,
  73     IOPMContextRetained = kIOPMContextRetained,
  74     IOPMConfigRetained  = kIOPMConfigRetained,
  75     IOPMNotPowerManaged = kIOPMNotPowerManaged,
  76     IOPMPagingAvailable = kIOPMPagingAvailable,
  77     IOPMSoftSleep       = kIOPMSoftSleep
  78 };
  79
  80
  81 enum {
  82     kIOPMNextHigherState        = 1,
  83     kIOPMHighestState           = 2,
  84     kIOPMNextLowerState         = 3,
  85     kIOPMLowestState            = 4
  86 };
  87
  88 enum {
  89     IOPMNextHigherState         = kIOPMNextHigherState,
  90     IOPMHighestState            = kIOPMHighestState,
  91     IOPMNextLowerState          = kIOPMNextLowerState,
  92     IOPMLowestState             = kIOPMLowestState
  93 };
  94
  95
  96
  97 enum {          // commands on power managment command queue
  98     kIOPMBroadcastAggressiveness = 1,
  99     kIOPMUnidleDevice
 100 };
 101
 102 enum {          // special value means "power consumption unknown"
 103     kIOPMUnknown = 0xFFFF
 104 };
 105
 106 // Power events
 107 enum {
 108   kClamshellClosedEventMask  = (1<<0),  // User closed lid
 109   kDockingBarEventMask       = (1<<1),  // OBSOLETE
 110   kACPlugEventMask           = (1<<2),  // User plugged or unplugged adapter
 111   kFrontPanelButtonEventMask = (1<<3),  // User hit the front panel button
 112   kBatteryStatusEventMask    = (1<<4)   // Battery status has changed
 113 };
 114
 115 // Power commands issued to root domain
 116 enum {
 117   kIOPMSleepNow                  = (1<<0),  // put machine to sleep now
 118   kIOPMAllowSleep                = (1<<1),  // allow idle sleep
 119   kIOPMPreventSleep              = (1<<2),  // do not allow idle sleep
 120   kIOPMPowerButton               = (1<<3),  // power button was pressed
 121   kIOPMClamshellClosed           = (1<<4),  // clamshell was closed
 122   kIOPMPowerEmergency            = (1<<5),  // battery dangerously low
 123   kIOPMDisableClamshell          = (1<<6),  // do not sleep on clamshell closure
 124   kIOPMEnableClamshell           = (1<<7),  // sleep on clamshell closure
 125   kIOPMProcessorSpeedChange      = (1<<8),  // change the processor speed
 126   kIOPMOverTemp                  = (1<<9)   // system dangerously hot
 127 };
 128                                         // Return codes
 129
 130 // PUBLIC power management features
 131 // NOTE: this is a direct port from classic, some of these bits
 132 //       are obsolete but are included for completeness
 133 enum {
 134   kPMHasWakeupTimerMask        = (1<<0),  // 1=wake timer is supported
 135   kPMHasSharedModemPortMask    = (1<<1),  // Not used
 136   kPMHasProcessorCyclingMask   = (1<<2),  // 1=processor cycling supported
 137   kPMMustProcessorCycleMask    = (1<<3),  // Not used
 138   kPMHasReducedSpeedMask       = (1<<4),  // 1=supports reduced processor speed
 139   kPMDynamicSpeedChangeMask    = (1<<5),  // 1=supports changing processor speed on the fly
 140   kPMHasSCSIDiskModeMask       = (1<<6),  // 1=supports using machine as SCSI drive
 141   kPMCanGetBatteryTimeMask     = (1<<7),  // 1=battery time can be calculated
 142   kPMCanWakeupOnRingMask       = (1<<8),  // 1=machine can wake on modem ring
 143   kPMHasDimmingSupportMask     = (1<<9),  // 1=has monitor dimming support
 144   kPMHasStartupTimerMask       = (1<<10), // 1=can program startup timer
 145   kPMHasChargeNotificationMask = (1<<11), // 1=client can determine charger status/get notifications
 146   kPMHasDimSuspendSupportMask  = (1<<12), // 1=can dim diplay to DPMS ('off') state
 147   kPMHasWakeOnNetActivityMask  = (1<<13), // 1=supports waking upon receipt of net packet
 148   kPMHasWakeOnLidMask          = (1<<14), // 1=can wake upon lid/case opening
 149   kPMCanPowerOffPCIBusMask     = (1<<15), // 1=can remove power from PCI bus on sleep
 150   kPMHasDeepSleepMask          = (1<<16), // 1=supports deep (hibernation) sleep
 151   kPMHasSleepMask              = (1<<17), // 1=machine support low power sleep (ala powerbooks)
 152   kPMSupportsServerModeAPIMask = (1<<18), // 1=supports reboot on AC resume for unexpected power loss
 153   kPMHasUPSIntegrationMask     = (1<<19)  // 1=supports incorporating UPS devices into power source calcs
 154 };
 155
 156 // PRIVATE power management features
 157 // NOTE: this is a direct port from classic, some of these bits
 158 //       are obsolete but are included for completeness.
 159 enum {
 160   kPMHasExtdBattInfoMask       = (1<<0),  // Not used
 161   kPMHasBatteryIDMask          = (1<<1),  // Not used
 162   kPMCanSwitchPowerMask        = (1<<2),  // Not used
 163   kPMHasCelsiusCyclingMask     = (1<<3),  // Not used
 164   kPMHasBatteryPredictionMask  = (1<<4),  // Not used
 165   kPMHasPowerLevelsMask        = (1<<5),  // Not used
 166   kPMHasSleepCPUSpeedMask      = (1<<6),  // Not used
 167   kPMHasBtnIntHandlersMask     = (1<<7),  // 1=supports individual button interrupt handlers
 168   kPMHasSCSITermPowerMask      = (1<<8),  // 1=supports SCSI termination power switch
 169   kPMHasADBButtonHandlersMask  = (1<<9),  // 1=supports button handlers via ADB
 170   kPMHasICTControlMask         = (1<<10), // 1=supports ICT control
 171   kPMHasLegacyDesktopSleepMask = (1<<11), // 1=supports 'doze' style sleep
 172   kPMHasDeepIdleMask           = (1<<12), // 1=supports Idle2 in hardware
 173   kPMOpenLidPreventsSleepMask  = (1<<13), // 1=open case prevent machine from sleeping
 174   kPMClosedLidCausesSleepMask  = (1<<14), // 1=case closed (clamshell closed) causes sleep
 175   kPMHasFanControlMask         = (1<<15), // 1=machine has software-programmable fan/thermostat controls
 176   kPMHasThermalControlMask     = (1<<16), // 1=machine supports thermal monitoring
 177   kPMHasVStepSpeedChangeMask   = (1<<17), // 1=machine supports processor voltage/clock change
 178   kPMEnvironEventsPolledMask   = (1<<18)  // 1=machine doesn't generate pmu env ints, we must poll instead
 179 };
 180
 181 // DEFAULT public and private features for machines whose device tree
 182 // does NOT contain this information (pre-Core99).
 183
 184 // For Cuda-based Desktops
 185
 186 #define kStdDesktopPMFeatures   kPMHasWakeupTimerMask         |\
 187                                 kPMHasProcessorCyclingMask    |\
 188                                 kPMHasDimmingSupportMask      |\
 189                                 kPMHasStartupTimerMask        |\
 190                                 kPMSupportsServerModeAPIMask  |\
 191                                 kPMHasUPSIntegrationMask
 192
 193 #define kStdDesktopPrivPMFeatures  kPMHasExtdBattInfoMask     |\
 194                                    kPMHasICTControlMask       |\
 195                                    kPMHasLegacyDesktopSleepMask
 196
 197 #define kStdDesktopNumBatteries 0
 198
 199 // For Wallstreet (PowerBook G3 Series 1998)
 200
 201 #define kWallstreetPMFeatures   kPMHasWakeupTimerMask         |\
 202                                 kPMHasProcessorCyclingMask    |\
 203                                 kPMHasReducedSpeedMask        |\
 204                                 kPMDynamicSpeedChangeMask     |\
 205                                 kPMHasSCSIDiskModeMask        |\
 206                                 kPMCanGetBatteryTimeMask      |\
 207                                 kPMHasDimmingSupportMask      |\
 208                                 kPMHasChargeNotificationMask  |\
 209                                 kPMHasDimSuspendSupportMask   |\
 210                                 kPMHasSleepMask
 211
 212 #define kWallstreetPrivPMFeatures  kPMHasExtdBattInfoMask      |\
 213                                    kPMHasBatteryIDMask         |\
 214                                    kPMCanSwitchPowerMask       |\
 215                                    kPMHasADBButtonHandlersMask |\
 216                                    kPMHasSCSITermPowerMask     |\
 217                                    kPMHasICTControlMask        |\
 218                                    kPMClosedLidCausesSleepMask |\
 219                                    kPMEnvironEventsPolledMask
 220
 221 #define kStdPowerBookPMFeatures      kWallstreetPMFeatures
 222 #define kStdPowerBookPrivPMFeatures  kWallstreetPrivPMFeatures
 223
 224 #define kStdPowerBookNumBatteries 2
 225
 226 // For 101 (PowerBook G3 Series 1999)
 227
 228 #define k101PMFeatures          kPMHasWakeupTimerMask         |\
 229                                 kPMHasProcessorCyclingMask    |\
 230                                 kPMHasReducedSpeedMask        |\
 231                                 kPMDynamicSpeedChangeMask     |\
 232                                 kPMHasSCSIDiskModeMask        |\
 233                                 kPMCanGetBatteryTimeMask      |\
 234                                 kPMHasDimmingSupportMask      |\
 235                                 kPMHasChargeNotificationMask  |\
 236                                 kPMHasDimSuspendSupportMask   |\
 237                                 kPMHasSleepMask               |\
 238                                 kPMHasUPSIntegrationMask
 239
 240 #define k101PrivPMFeatures      kPMHasExtdBattInfoMask        |\
 241                                 kPMHasBatteryIDMask           |\
 242                                 kPMCanSwitchPowerMask         |\
 243                                 kPMHasADBButtonHandlersMask   |\
 244                                 kPMHasSCSITermPowerMask       |\
 245                                 kPMHasICTControlMask          |\
 246                                 kPMClosedLidCausesSleepMask   |\
 247                                 kPMEnvironEventsPolledMask
 248
 249 #define IOPMNoErr               0       // normal return
 250
 251                         // returned by powerStateWillChange and powerStateDidChange:
 252 #define IOPMAckImplied          0       // acknowledgement of power state change is implied
 253 #define IOPMWillAckLater        1       // acknowledgement of power state change will come later
 254
 255                         // returned by requestDomainState
 256 #define IOPMBadSpecification    4       // unrecognized specification parameter
 257 #define IOPMNoSuchState         5       // no power state matches search specification
 258
 259 #define IOPMCannotRaisePower    6       // a device cannot change its power for some reason
 260
 261                         // returned by changeStateTo
 262 #define IOPMParameterError      7       // requested state doesn't exist
 263 #define IOPMNotYetInitialized   8       // device not yet fully hooked into power management "graph"
 264
 265
 266                                                 // used by Root Domain UserClient
 267
 268 enum {
 269     kPMGeneralAggressiveness = 0,
 270     kPMMinutesToDim,
 271     kPMMinutesToSpinDown,
 272     kPMMinutesToSleep,
 273     kPMEthernetWakeOnLANSettings,
 274     kPMSetProcessorSpeed,
 275     kPMPowerSource
 276 };
 277 #define kMaxType kPMEthernetWakeOnLANSettings
 278
 279 // SetAggressiveness values for the kPMPowerSource aggressiveness type
 280 enum {
 281     kIOPMInternalPower = 1,
 282     kIOPMExternalPower
 283 };
 284
 285 #define kAppleClamshellStateKey           "AppleClamshellState"
 286 #define kIOREMSleepEnabledKey             "REMSleepEnabled"
 287
 288 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo
 289 #define kIOBatteryInfoKey               "IOBatteryInfo"
 290 #define kIOBatteryCurrentChargeKey      "Current"
 291 #define kIOBatteryCapacityKey           "Capacity"
 292 #define kIOBatteryFlagsKey              "Flags"
 293 #define kIOBatteryVoltageKey            "Voltage"
 294 #define kIOBatteryAmperageKey           "Amperage"
 295
 296 enum {
 297     kIOBatteryInstalled         = (1 << 2),
 298     kIOBatteryCharge            = (1 << 1),
 299     kIOBatteryChargerConnect    = (1 << 0)
 300 };
 301
 302 // Private power management message indicating battery data has changed
 303 // Indicates new data resides in the IORegistry
 304 #define kIOPMMessageBatteryStatusHasChanged         iokit_family_msg(sub_iokit_pmu, 0x100)
 305
 306 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU
 307 // through newer user space IOPMSchedulePowerEvent API
 308 #define kIOPMUMessageLegacyAutoWake                 iokit_family_msg(sub_iokit_pmu, 0x200)
 309 #define kIOPMUMessageLegacyAutoPower                    iokit_family_msg(sub_iokit_pmu, 0x210)
 310
 311 // These flags are deprecated. Use the version with the kIOPM prefix below.
 312 enum {
 313   kACInstalled      = kIOBatteryChargerConnect,
 314   kBatteryCharging  = kIOBatteryCharge,
 315   kBatteryInstalled = kIOBatteryInstalled,
 316   kUPSInstalled     = (1<<3),
 317   kBatteryAtWarn    = (1<<4),
 318   kBatteryDepleted  = (1<<5),
 319   kACnoChargeCapability = (1<<6),     // AC adapter cannot charge battery
 320   kRawLowBattery    = (1<<7),         // used only by  Platform Expert
 321   kForceLowSpeed    = (1<<8)         // set by Platfm Expert, chk'd by Pwr Plugin};
 322 };
 323
 324 // For use with IOPMPowerSource bFlags
 325 #define IOPM_POWER_SOURCE_REV   2
 326 enum {
 327   kIOPMACInstalled      = kIOBatteryChargerConnect,
 328   kIOPMBatteryCharging  = kIOBatteryCharge,
 329   kIOPMBatteryInstalled = kIOBatteryInstalled,
 330   kIOPMUPSInstalled     = (1<<3),
 331   kIOPMBatteryAtWarn    = (1<<4),
 332   kIOPMBatteryDepleted  = (1<<5),
 333   kIOPMACnoChargeCapability = (1<<6),     // AC adapter cannot charge battery
 334   kIOPMRawLowBattery    = (1<<7),         // used only by  Platform Expert
 335   kIOPMForceLowSpeed    = (1<<8),         // set by Platfm Expert, chk'd by Pwr Plugin
 336   kIOPMClosedClamshell  = (1<<9),         // set by PMU - reflects state of the clamshell
 337   kIOPMClamshellStateOnWake = (1<<10)     // used only by Platform Expert
 338 };
 339
 340
 341 // **********************************************
 342 // Internal power management data structures
 343 // **********************************************
 344
 345 #if KERNEL && __cplusplus
 346 class IOService;
 347
 348 enum {
 349     kIOPowerEmergencyLevel = 1000
 350 };
 351
 352 enum {
 353     kIOPMSubclassPolicy,
 354     kIOPMSuperclassPolicy1
 355 };
 356
 357 struct stateChangeNote{
 358     IOPMPowerFlags      stateFlags;
 359     unsigned long       stateNum;
 360     void *              powerRef;
 361 };
 362 typedef struct stateChangeNote stateChangeNote;
 363
 364 struct IOPowerStateChangeNotification {
 365     void *              powerRef;
 366     unsigned long       returnValue;
 367     unsigned long       stateNumber;
 368     IOPMPowerFlags      stateFlags;
 369 };
 370 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification;
 371 typedef IOPowerStateChangeNotification sleepWakeNote;
 372
 373 extern void IOPMRegisterDevice(const char *, IOService *);
 374 #endif /* KERNEL && __cplusplus */
 375
 376 #endif /* ! _IOKIT_IOPM_H */
 377