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