iokit/IOKit/pwr_mgt/IOPM.h

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