2 * Copyright (c) 1998-2005 Apple Computer, Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
31 #include <IOKit/IOTypes.h>
32 #include <IOKit/IOMessage.h>
33 #include <IOKit/IOReturn.h>
36 #include <IOKit/pwr_mgt/IOPMDeprecated.h>
40 @abstract Defines power management constants and keys used by both in-kernel and user space power management.
41 @discussion IOPM.h defines a range of power management constants used in several in-kernel and user space APIs. Most significantly, the IOPMPowerFlags used to specify the fields of an IOPMPowerState struct are defined here.
43 Most of the constants defined in IOPM.h are deprecated or for Apple internal use only, and are not elaborated on in headerdoc.
47 kIOPMMaxPowerStates
= 10,
48 IOPMMaxPowerStates
= kIOPMMaxPowerStates
51 /*! @enum IOPMPowerFlags
52 @abstract Bits are used in defining capabilityFlags, inputPowerRequirements, and outputPowerCharacter in the IOPMPowerState structure.
53 @discussion These bits may be bitwise-OR'd together in the IOPMPowerState capabilityFlags field, the outputPowerCharacter field, and/or the inputPowerRequirement field.
55 The comments clearly mark whether each flag should be used in the capabilityFlags field, outputPowerCharacter field, and inputPowerRequirement field, or all three.
57 The value of capabilityFlags, inputPowerRequirement or outputPowerCharacter may be 0. Most drivers implement their 'OFF' state, used when asleep, by defininf each of the 3 fields as 0.
59 The bits listed below are only the most common bits used to define a device's power states. Your device's IO family may require that your device specify other input or output power flags to interact properly. Consult family-specific documentation to determine if your IOPower plane parents or children require other power flags; they probably don't.
61 @constant kIOPMPowerOn Indicates the device is on, requires power, and provides power. Useful as a: Capability, InputPowerRequirement, OutputPowerCharacter
63 @constant kIOPMDeviceUsable Indicates the device is usable in this state. Useful only as a Capability
65 @constant kIOPMLowPower
66 Indicates device is in a low power state. May be bitwis-OR'd together
67 with kIOPMDeviceUsable flag, to indicate the device is still usable.
69 A device with a capability of kIOPMLowPower may:
70 Require either 0 or kIOPMPowerOn from its power parent
71 Offer either kIOPMLowPower, kIOPMPowerOn, or 0 (no power at all)
72 to its power plane children.
74 Useful only as a Capability, although USB drivers should consult USB family documentation for other valid circumstances to use the kIOPMLowPower bit.
76 @constant kIOPMPreventIdleSleep
77 In the capability field of a power state, disallows idle system sleep while the device is in that state.
79 For example, displays and disks set this capability for their ON power state; since the system may not idle sleep while the display (and thus keyboard or mouse) or the disk is active.
81 Useful only as a Capability.
83 @constant kIOPMSleepCapability
84 Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities.
86 @constant kIOPMRestartCapability
87 Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities.
90 Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities.
92 @constant kIOPMRestart
93 Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities.
95 typedef unsigned long IOPMPowerFlags
;
97 kIOPMPowerOn
= 0x00000002,
98 kIOPMDeviceUsable
= 0x00008000,
99 kIOPMLowPower
= 0x00010000,
100 kIOPMPreventIdleSleep
= 0x00000040,
101 kIOPMSleepCapability
= 0x00000004,
102 kIOPMRestartCapability
= 0x00000080,
103 kIOPMSleep
= 0x00000001,
104 kIOPMRestart
= 0x00000080
108 * Private IOPMPowerFlags
111 * Not for use with non-Apple drivers
112 * Their behavior is undefined
115 kIOPMClockNormal
= 0x0004,
116 kIOPMClockRunning
= 0x0008,
117 kIOPMPreventSystemSleep
= 0x0010,
119 kIOPMChildClamp
= 0x0080,
120 kIOPMChildClamp2
= 0x0200,
121 kIOPMNotPowerManaged
= 0x0800
126 * Deprecated IOPMPowerFlags
127 * Their behavior is undefined when used in IOPMPowerState
128 * Capability, InputPowerRequirement, or OutputPowerCharacter fields.
131 kIOPMMaxPerformance
= 0x4000,
132 kIOPMPassThrough
= 0x0100,
133 kIOPMAuxPowerOn
= 0x0020,
134 kIOPMNotAttainable
= 0x0001,
135 kIOPMContextRetained
= 0x2000,
136 kIOPMConfigRetained
= 0x1000,
137 kIOPMStaticPowerValid
= 0x0800,
138 kIOPMSoftSleep
= 0x0400,
139 kIOPMCapabilitiesMask
= kIOPMPowerOn
| kIOPMDeviceUsable
|
140 kIOPMMaxPerformance
| kIOPMContextRetained
|
141 kIOPMConfigRetained
| kIOPMSleepCapability
|
142 kIOPMRestartCapability
146 * Support for old names of IOPMPowerFlag constants
149 IOPMNotAttainable
= kIOPMNotAttainable
,
150 IOPMPowerOn
= kIOPMPowerOn
,
151 IOPMClockNormal
= kIOPMClockNormal
,
152 IOPMClockRunning
= kIOPMClockRunning
,
153 IOPMAuxPowerOn
= kIOPMAuxPowerOn
,
154 IOPMDeviceUsable
= kIOPMDeviceUsable
,
155 IOPMMaxPerformance
= kIOPMMaxPerformance
,
156 IOPMContextRetained
= kIOPMContextRetained
,
157 IOPMConfigRetained
= kIOPMConfigRetained
,
158 IOPMNotPowerManaged
= kIOPMNotPowerManaged
,
159 IOPMSoftSleep
= kIOPMSoftSleep
164 kIOPMNextHigherState
= 1,
165 kIOPMHighestState
= 2,
166 kIOPMNextLowerState
= 3,
171 IOPMNextHigherState
= kIOPMNextHigherState
,
172 IOPMHighestState
= kIOPMHighestState
,
173 IOPMNextLowerState
= kIOPMNextLowerState
,
174 IOPMLowestState
= kIOPMLowestState
177 // Internal commands used by power managment command queue
179 kIOPMBroadcastAggressiveness
= 1,
183 // Power consumption unknown value
185 kIOPMUnknown
= 0xFFFF
188 /*******************************************************************************
190 * Root Domain property keys of interest
192 ******************************************************************************/
194 /* AppleClamshellState
195 * reflects the state of the clamshell (lid) on a portable.
196 * It has a boolean value.
197 * true == clamshell is closed
198 * false == clamshell is open
199 * not present == no clamshell on this hardware
201 #define kAppleClamshellStateKey "AppleClamshellState"
203 /* AppleClamshellCausesSleep
204 * reflects the clamshell close behavior on a portable.
205 * It has a boolean value.
206 * true == system will sleep when clamshell is closed
207 * false == system will not sleep on clamshell close
208 * (typically external display mode)
209 * not present == no clamshell on this hardware
211 #define kAppleClamshellCausesSleepKey "AppleClamshellCausesSleep"
213 /*******************************************************************************
215 * Root Domain general interest messages
217 ******************************************************************************/
219 /* kIOPMMessageClamshellStateChange
220 * Delivered as a general interest notification on the IOPMrootDomain
221 * IOPMrootDomain sends this message when state of either AppleClamshellState
222 * or AppleClamshellCausesSleep changes. If this clamshell change results in
223 * a sleep, the sleep will initiate soon AFTER delivery of this message.
224 * The state of both variables is encoded in a bitfield argument sent with
225 * the message. Check bits 0 and 1 using kClamshellStateBit & kClamshellSleepBit
228 kClamshellStateBit
= (1 << 0),
229 kClamshellSleepBit
= (1 << 1)
232 #define kIOPMMessageClamshellStateChange \
233 iokit_family_msg(sub_iokit_powermanagement, 0x100)
235 /* kIOPMMessageFeatureChange
236 * Delivered when the set of supported features ("Supported Features" dictionary
237 * under IOPMrootDomain registry) changes in some way. Typically addition or
238 * removal of a supported feature.
239 * RootDomain passes no argument with this message.
241 #define kIOPMMessageFeatureChange \
242 iokit_family_msg(sub_iokit_powermanagement, 0x110)
244 /* kIOPMMessageInflowDisableCancelled
245 * The battery has drained completely to its "Fully Discharged" state.
246 * If a user process has disabled battery inflow for battery
247 * calibration, we forcibly re-enable Inflow at this point.
248 * If inflow HAS been forcibly re-enabled, bit 0
249 * (kInflowForciblyEnabledBit) will be set.
252 kInflowForciblyEnabledBit
= (1 << 0)
255 #define kIOPMMessageInternalBatteryFullyDischarged \
256 iokit_family_msg(sub_iokit_powermanagement, 0x120)
259 /*******************************************************************************
261 * Power commands issued to root domain
263 * These commands are issued from system drivers only:
264 * ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily
266 ******************************************************************************/
268 kIOPMSleepNow
= (1<<0), // put machine to sleep now
269 kIOPMAllowSleep
= (1<<1), // allow idle sleep
270 kIOPMPreventSleep
= (1<<2), // do not allow idle sleep
271 kIOPMPowerButton
= (1<<3), // power button was pressed
272 kIOPMClamshellClosed
= (1<<4), // clamshell was closed
273 kIOPMPowerEmergency
= (1<<5), // battery dangerously low
274 kIOPMDisableClamshell
= (1<<6), // do not sleep on clamshell closure
275 kIOPMEnableClamshell
= (1<<7), // sleep on clamshell closure
276 kIOPMProcessorSpeedChange
= (1<<8), // change the processor speed
277 kIOPMOverTemp
= (1<<9), // system dangerously hot
278 kIOPMClamshellOpened
= (1<<10) // clamshell was opened
281 /*******************************************************************************
283 * Power Management Return Codes
285 ******************************************************************************/
288 // Returned by powerStateWillChange and powerStateDidChange:
289 // Immediate acknowledgement of power state change
291 // Acknowledgement of power state change will come later
292 kIOPMWillAckLater
= 1,
294 // Returned by requestDomainState:
295 // Unrecognized specification parameter
296 kIOPMBadSpecification
= 4,
297 // No power state matches search specification
298 kIOPMNoSuchState
= 5,
300 // Device cannot change its power for some reason
301 kIOPMCannotRaisePower
= 6,
303 // Returned by changeStateTo:
304 // Requested state doesn't exist
305 kIOPMParameterError
= 7,
306 // Device not yet fully hooked into power management
307 kIOPMNotYetInitialized
= 8,
309 // And the old constants; deprecated
310 IOPMNoErr
= kIOPMNoErr
,
311 IOPMAckImplied
= kIOPMAckImplied
,
312 IOPMWillAckLater
= kIOPMWillAckLater
,
313 IOPMBadSpecification
= kIOPMBadSpecification
,
314 IOPMNoSuchState
= kIOPMNoSuchState
,
315 IOPMCannotRaisePower
= kIOPMCannotRaisePower
,
316 IOPMParameterError
= kIOPMParameterError
,
317 IOPMNotYetInitialized
= kIOPMNotYetInitialized
321 // IOPMPowerSource class descriptive strings
322 // Power Source state is published as properties to the IORegistry under these
324 #define kIOPMPSExternalConnectedKey "ExternalConnected"
325 #define kIOPMPSExternalChargeCapableKey "ExternalChargeCapable"
326 #define kIOPMPSBatteryInstalledKey "BatteryInstalled"
327 #define kIOPMPSIsChargingKey "IsCharging"
328 #define kIOPMFullyChargedKey "FullyCharged"
329 #define kIOPMPSAtWarnLevelKey "AtWarnLevel"
330 #define kIOPMPSAtCriticalLevelKey "AtCriticalLevel"
331 #define kIOPMPSCurrentCapacityKey "CurrentCapacity"
332 #define kIOPMPSMaxCapacityKey "MaxCapacity"
333 #define kIOPMPSDesignCapacityKey "DesignCapacity"
334 #define kIOPMPSTimeRemainingKey "TimeRemaining"
335 #define kIOPMPSAmperageKey "Amperage"
336 #define kIOPMPSVoltageKey "Voltage"
337 #define kIOPMPSCycleCountKey "CycleCount"
338 #define kIOPMPSMaxErrKey "MaxErr"
339 #define kIOPMPSAdapterInfoKey "AdapterInfo"
340 #define kIOPMPSLocationKey "Location"
341 #define kIOPMPSErrorConditionKey "ErrorCondition"
342 #define kIOPMPSManufacturerKey "Manufacturer"
343 #define kIOPMPSManufactureDateKey "ManufactureDate"
344 #define kIOPMPSModelKey "Model"
345 #define kIOPMPSSerialKey "Serial"
346 #define kIOPMDeviceNameKey "DeviceName"
347 #define kIOPMPSLegacyBatteryInfoKey "LegacyBatteryInfo"
348 #define kIOPMPSBatteryHealthKey "BatteryHealth"
349 #define kIOPMPSHealthConfidenceKey "HealthConfidence"
350 #define kIOPMPSCapacityEstimatedKey "CapacityEstimated"
352 // Definitions for battery location, in case of multiple batteries.
353 // A location of 0 is unspecified
354 // Location is undefined for single battery systems
356 kIOPMPSLocationLeft
= 1001,
357 kIOPMPSLocationRight
= 1002
360 // Battery quality health types, specified by BatteryHealth and HealthConfidence
361 // properties in an IOPMPowerSource battery kext.
363 kIOPMUndefinedValue
= 0,
369 // Battery's time remaining estimate is invalid this long (seconds) after a wake
370 #define kIOPMPSInvalidWakeSecondsKey "BatteryInvalidWakeSeconds"
372 // Battery must wait this long (seconds) after being completely charged before
373 // the battery is settled.
374 #define kIOPMPSPostChargeWaitSecondsKey "PostChargeWaitSeconds"
376 // Battery must wait this long (seconds) after being completely discharged
377 // before the battery is settled.
378 #define kIOPMPSPostDishargeWaitSecondsKey "PostDischargeWaitSeconds"
382 // PM Settings Controller setting types
383 // Settings types used primarily with:
384 // IOPMrootDomain::registerPMSettingController
385 // The values are identical to the similarly named keys for use in user space
386 // PM settings work. Those keys are defined in IOPMLibPrivate.h.
387 #define kIOPMSettingWakeOnRingKey "Wake On Modem Ring"
388 #define kIOPMSettingRestartOnPowerLossKey "Automatic Restart On Power Loss"
389 #define kIOPMSettingWakeOnACChangeKey "Wake On AC Change"
390 #define kIOPMSettingSleepOnPowerButtonKey "Sleep On Power Button"
391 #define kIOPMSettingWakeOnClamshellKey "Wake On Clamshell Open"
392 #define kIOPMSettingReduceBrightnessKey "ReduceBrightness"
393 #define kIOPMSettingDisplaySleepUsesDimKey "Display Sleep Uses Dim"
394 #define kIOPMSettingTimeZoneOffsetKey "TimeZoneOffsetSeconds"
395 #define kIOPMSettingMobileMotionModuleKey "MobileMotionModule"
397 // Setting controlling drivers can register to receive scheduled wake data
398 // Either in "CF seconds" type, or structured calendar data in a formatted
399 // IOPMCalendarStruct defined below.
400 #define kIOPMSettingAutoWakeSecondsKey "wake"
401 #define kIOPMSettingAutoWakeCalendarKey "WakeByCalendarDate"
402 #define kIOPMSettingAutoPowerSecondsKey "poweron"
403 #define kIOPMSettingAutoPowerCalendarKey "PowerByCalendarDate"
405 // Debug seconds auto wake
406 // Used by sleep cycling debug tools
407 #define kIOPMSettingDebugWakeRelativeKey "WakeRelativeToSleep"
408 #define kIOPMSettingDebugPowerRelativeKey "PowerRelativeToShutdown"
410 struct IOPMCalendarStruct
{
418 typedef struct IOPMCalendarStruct IOPMCalendarStruct
;
420 // SetAggressiveness types
422 kPMGeneralAggressiveness
= 0,
424 kPMMinutesToSpinDown
,
426 kPMEthernetWakeOnLANSettings
,
427 kPMSetProcessorSpeed
,
430 kPMLastAggressivenessType
432 #define kMaxType (kPMLastAggressivenessType-1)
434 // SetAggressiveness values for the kPMPowerSource aggressiveness type
436 kIOPMInternalPower
= 1,
440 #define kIOREMSleepEnabledKey "REMSleepEnabled"
442 // Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo
443 #define kIOBatteryInfoKey "IOBatteryInfo"
444 #define kIOBatteryCurrentChargeKey "Current"
445 #define kIOBatteryCapacityKey "Capacity"
446 #define kIOBatteryFlagsKey "Flags"
447 #define kIOBatteryVoltageKey "Voltage"
448 #define kIOBatteryAmperageKey "Amperage"
449 #define kIOBatteryCycleCountKey "Cycle Count"
452 kIOBatteryInstalled
= (1 << 2),
453 kIOBatteryCharge
= (1 << 1),
454 kIOBatteryChargerConnect
= (1 << 0)
458 // Private power management message indicating battery data has changed
459 // Indicates new data resides in the IORegistry
460 #define kIOPMMessageBatteryStatusHasChanged iokit_family_msg(sub_iokit_pmu, 0x100)
462 // Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU
463 // through newer user space IOPMSchedulePowerEvent API
464 #define kIOPMUMessageLegacyAutoWake iokit_family_msg(sub_iokit_pmu, 0x200)
465 #define kIOPMUMessageLegacyAutoPower iokit_family_msg(sub_iokit_pmu, 0x210)
467 // For use with IOPMPowerSource bFlags
468 #define IOPM_POWER_SOURCE_REV 2
470 kIOPMACInstalled
= kIOBatteryChargerConnect
,
471 kIOPMBatteryCharging
= kIOBatteryCharge
,
472 kIOPMBatteryInstalled
= kIOBatteryInstalled
,
473 kIOPMUPSInstalled
= (1<<3),
474 kIOPMBatteryAtWarn
= (1<<4),
475 kIOPMBatteryDepleted
= (1<<5),
476 kIOPMACnoChargeCapability
= (1<<6), // AC adapter cannot charge battery
477 kIOPMRawLowBattery
= (1<<7), // used only by Platform Expert
478 kIOPMForceLowSpeed
= (1<<8), // set by Platfm Expert, chk'd by Pwr Plugin
479 kIOPMClosedClamshell
= (1<<9), // set by PMU - reflects state of the clamshell
480 kIOPMClamshellStateOnWake
= (1<<10) // used only by Platform Expert
484 // **********************************************
485 // Internal power management data structures
486 // **********************************************
488 #if KERNEL && __cplusplus
492 kIOPowerEmergencyLevel
= 1000
497 kIOPMSuperclassPolicy1
500 struct stateChangeNote
{
501 IOPMPowerFlags stateFlags
;
502 unsigned long stateNum
;
505 typedef struct stateChangeNote stateChangeNote
;
507 struct IOPowerStateChangeNotification
{
509 unsigned long returnValue
;
510 unsigned long stateNumber
;
511 IOPMPowerFlags stateFlags
;
513 typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification
;
514 typedef IOPowerStateChangeNotification sleepWakeNote
;
516 extern void IOPMRegisterDevice(const char *, IOService
*);
517 #endif /* KERNEL && __cplusplus */
519 #endif /* ! _IOKIT_IOPM_H */