1/*
2 * Copyright (c) 1998-2005 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#include <IOKit/IOTypes.h>
32#include <IOKit/IOMessage.h>
33#include <IOKit/IOReturn.h>
34
35/*! @header IOPM.h
36    @abstract Defines power management constants and keys used by both in-kernel and user space power management.
37    @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.
38
39    Most of the constants defined in IOPM.h are deprecated or for Apple internal use only, and are not elaborated on in headerdoc.
40*/
41
42enum {
43    kIOPMMaxPowerStates = 10,
44    IOPMMaxPowerStates = kIOPMMaxPowerStates
45};
46
47/*! @enum IOPMPowerFlags
48    @abstract Bits are used in defining capabilityFlags, inputPowerRequirements, and outputPowerCharacter in the IOPMPowerState structure.
49    @discussion These bits may be bitwise-OR'd together in the IOPMPowerState capabilityFlags field, the outputPowerCharacter field, and/or the inputPowerRequirement field.
50
51    The comments clearly mark whether each flag should be used in the capabilityFlags field, outputPowerCharacter field, and inputPowerRequirement field, or all three.
52
53    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.
54
55    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.
56
57    @constant kIOPMPowerOn Indicates the device is on, requires power, and provides power. Useful as a: Capability, InputPowerRequirement, OutputPowerCharacter
58
59    @constant kIOPMDeviceUsable Indicates the device is usable in this state. Useful only as a Capability
60
61    @constant kIOPMLowPower
62    Indicates device is in a low power state. May be bitwis-OR'd together
63    with kIOPMDeviceUsable flag, to indicate the device is still usable.
64
65    A device with a capability of kIOPMLowPower may:
66       Require either 0 or kIOPMPowerOn from its power parent
67       Offer either kIOPMLowPower, kIOPMPowerOn, or 0 (no power at all)
68         to its power plane children.
69
70    Useful only as a Capability, although USB drivers should consult USB family documentation for other valid circumstances to use the kIOPMLowPower bit.
71
72    @constant kIOPMPreventIdleSleep
73    In the capability field of a power state, disallows idle system sleep while the device is in that state.
74
75    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.
76
77    Useful only as a Capability.
78
79    @constant kIOPMSleepCapability
80    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.
81
82    @constant kIOPMRestartCapability
83    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.
84
85    @constant kIOPMSleep
86    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.
87
88    @constant kIOPMRestart
89    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
91    @constant kIOPMInitialDeviceState
92    Indicates the initial power state for the device. If <code>initialPowerStateForDomainState()</code> returns a power state with this flag set in the capability field, then the initial power change is performed without calling the driver's <code>setPowerState()</code>.
93
94    @constant kIOPMRootDomainState
95    An indication that the power flags represent the state of the root power
96    domain. This bit must not be set in the IOPMPowerState structure.
97    Power Management may pass this bit to initialPowerStateForDomainState()
98    or powerStateForDomainState() to map from a global system state to the
99    desired device state.
100*/
101typedef unsigned long IOPMPowerFlags;
102enum {
103    kIOPMPowerOn                    = 0x00000002,
104    kIOPMDeviceUsable               = 0x00008000,
105    kIOPMLowPower                   = 0x00010000,
106    kIOPMPreventIdleSleep           = 0x00000040,
107    kIOPMSleepCapability            = 0x00000004,
108    kIOPMRestartCapability          = 0x00000080,
109    kIOPMSleep                      = 0x00000001,
110    kIOPMRestart                    = 0x00000080,
111    kIOPMInitialDeviceState         = 0x00000100,
112    kIOPMRootDomainState            = 0x00000200
113};
114
115/*
116 * Private IOPMPowerFlags
117 *
118 * For Apple use only
119 * Not for use with non-Apple drivers
120 * Their behavior is undefined
121 */
122enum {
123    kIOPMClockNormal                = 0x0004,
124    kIOPMClockRunning               = 0x0008,
125    kIOPMPreventSystemSleep         = 0x0010,
126    kIOPMDoze                       = 0x0400,
127    kIOPMChildClamp                 = 0x0080,
128    kIOPMChildClamp2                = 0x0200,
129    kIOPMNotPowerManaged            = 0x0800
130};
131
132/*
133 * Deprecated IOPMPowerFlags
134 * Their behavior is undefined when used in IOPMPowerState
135 * Capability, InputPowerRequirement, or OutputPowerCharacter fields.
136 */
137enum {
138    kIOPMMaxPerformance             = 0x4000,
139    kIOPMPassThrough                = 0x0100,
140    kIOPMAuxPowerOn                 = 0x0020,
141    kIOPMNotAttainable              = 0x0001,
142    kIOPMContextRetained            = 0x2000,
143    kIOPMConfigRetained             = 0x1000,
144    kIOPMStaticPowerValid           = 0x0800,
145    kIOPMSoftSleep                  = 0x0400,
146    kIOPMCapabilitiesMask =     kIOPMPowerOn | kIOPMDeviceUsable |
147                                kIOPMMaxPerformance | kIOPMContextRetained |
148                                kIOPMConfigRetained | kIOPMSleepCapability |
149                                kIOPMRestartCapability
150};
151
152/*
153 * Support for old names of IOPMPowerFlag constants
154 */
155enum {
156    IOPMNotAttainable           = kIOPMNotAttainable,
157    IOPMPowerOn                 = kIOPMPowerOn,
158    IOPMClockNormal             = kIOPMClockNormal,
159    IOPMClockRunning            = kIOPMClockRunning,
160    IOPMAuxPowerOn              = kIOPMAuxPowerOn,
161    IOPMDeviceUsable            = kIOPMDeviceUsable,
162    IOPMMaxPerformance          = kIOPMMaxPerformance,
163    IOPMContextRetained         = kIOPMContextRetained,
164    IOPMConfigRetained          = kIOPMConfigRetained,
165    IOPMNotPowerManaged         = kIOPMNotPowerManaged,
166    IOPMSoftSleep               = kIOPMSoftSleep
167};
168
169
170enum {
171    kIOPMNextHigherState        = 1,
172    kIOPMHighestState           = 2,
173    kIOPMNextLowerState         = 3,
174    kIOPMLowestState            = 4
175};
176
177enum {
178    IOPMNextHigherState         = kIOPMNextHigherState,
179    IOPMHighestState            = kIOPMHighestState,
180    IOPMNextLowerState          = kIOPMNextLowerState,
181    IOPMLowestState             = kIOPMLowestState
182};
183
184// Internal commands used by power managment command queue
185enum {
186    kIOPMBroadcastAggressiveness = 1,
187    kIOPMUnidleDevice
188};
189
190// Power consumption unknown value
191enum {
192    kIOPMUnknown = 0xFFFF
193};
194
195/*******************************************************************************
196 *
197 * Root Domain property keys of interest
198 *
199 ******************************************************************************/
200
201/* AppleClamshellState
202 * reflects the state of the clamshell (lid) on a portable.
203 * It has a boolean value.
204 *  true        == clamshell is closed
205 *  false       == clamshell is open
206 *  not present == no clamshell on this hardware
207 */
208#define kAppleClamshellStateKey             "AppleClamshellState"
209
210/* AppleClamshellCausesSleep
211 * reflects the clamshell close behavior on a portable.
212 * It has a boolean value.
213 *  true        == system will sleep when clamshell is closed
214 *  false       == system will not sleep on clamshell close
215 *                  (typically external display mode)
216 *  not present == no clamshell on this hardware
217 */
218#define kAppleClamshellCausesSleepKey       "AppleClamshellCausesSleep"
219
220/* kIOPMSleepWakeUUIDKey
221 * Key refers to a CFStringRef that will uniquely identify
222 * a sleep/wake cycle for logging & tracking.
223 * The key becomes valid at the beginning of a sleep cycle - before we
224 * initiate any sleep/wake notifications.
225 * The key becomes invalid at the completion of a system wakeup. The
226 * property will not be present in the IOPMrootDomain's registry entry
227 * when it is invalid.
228 *
229 * See IOPMrootDomain notification kIOPMMessageSleepWakeUUIDChange
230 */
231 #define kIOPMSleepWakeUUIDKey              "SleepWakeUUID"
232
233/* kIOPMBootSessionUUIDKey
234 * Key refers to a CFStringRef that will uniquely identify
235 * a boot cycle.
236 * The key becomes valid at boot time and remains valid
237 * till shutdown. The property value will remain same across
238 * sleep/wake/hibernate cycle.
239 */
240#define kIOPMBootSessionUUIDKey             "BootSessionUUID"
241
242/* kIOPMDeepSleepEnabledKey
243 * Indicates the Deep Sleep enable state.
244 * It has a boolean value.
245 *  true        == Deep Sleep is enabled
246 *  false       == Deep Sleep is disabled
247 *  not present == Deep Sleep is not supported on this hardware
248 */
249#define kIOPMDeepSleepEnabledKey            "Standby Enabled"
250
251/* kIOPMDeepSleepDelayKey
252 * Key refers to a CFNumberRef that represents the delay in seconds before
253 * entering Deep Sleep state. The property is not present if Deep Sleep is
254 * unsupported.
255 */
256#define kIOPMDeepSleepDelayKey              "Standby Delay"
257
258/* kIOPMDestroyFVKeyOnStandbyKey
259 * Specifies if FileVault key can be stored when going to standby mode
260 * It has a boolean value,
261 *  true        == Destroy FV key when going to standby mode
262 *  false       == Retain FV key when going to standby mode
263 *  not present == Retain FV key when going to standby mode
264 */
265#define kIOPMDestroyFVKeyOnStandbyKey       "DestroyFVKeyOnStandby"
266
267/*******************************************************************************
268 *
269 * Properties that can control power management behavior
270 *
271 ******************************************************************************/
272
273/* kIOPMResetPowerStateOnWakeKey
274 * If an IOService publishes this key with the value of kOSBooleanTrue,
275 * then PM will disregard the influence from changePowerStateToPriv() or
276 * any activity tickles that occurred before system sleep when resolving
277 * the initial device power state on wake. Influences from power children
278 * and changePowerStateTo() are not eliminated. At the earliest opportunity
279 * upon system wake, PM will query the driver for a new power state to be
280 * installed as the initial changePowerStateToPriv() influence, by calling
281 * initialPowerStateForDomainState() with both kIOPMRootDomainState and
282 * kIOPMPowerOn flags set. The default implementation will always return
283 * the lowest power state. Drivers can override this default behavior to
284 * immediately raise the power state when there are work blocked on the
285 * power change, and cannot afford to wait until the next activity tickle.
286 * This property should be statically added to a driver's plist or set at
287 * runtime before calling PMinit().
288 */
289#define kIOPMResetPowerStateOnWakeKey       "IOPMResetPowerStateOnWake"
290
291/*******************************************************************************
292 *
293 * Driver PM Assertions
294 *
295 ******************************************************************************/
296
297/* Driver Assertion bitfield description
298 * Driver PM assertions are defined by these bits.
299 */
300enum {
301    /*! kIOPMDriverAssertionCPUBit
302     * When set, PM kernel will prefer to leave the CPU and core hardware
303     * running in "Dark Wake" state, instead of sleeping.
304     */
305    kIOPMDriverAssertionCPUBit                      = 0x01,
306
307    /*! kIOPMDriverAssertionUSBExternalDeviceBit
308     * When set, driver is informing PM that an external USB device is attached.
309     */
310    kIOPMDriverAssertionUSBExternalDeviceBit        = 0x04,
311
312    /*! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
313     * When set, driver is informing PM that a Bluetooth HID device is paired.
314     */
315    kIOPMDriverAssertionBluetoothHIDDevicePairedBit = 0x08,
316
317    /*! kIOPMDriverAssertionExternalMediaMountedBit
318     * When set, driver is informing PM that an external media is mounted.
319     */
320    kIOPMDriverAssertionExternalMediaMountedBit     = 0x10,
321
322    /*! kIOPMDriverAssertionReservedBit5
323     * Reserved for Thunderbolt.
324     */
325    kIOPMDriverAssertionReservedBit5                = 0x20,
326
327    /*! kIOPMDriverAssertionPreventDisplaySleepBit
328     * When set, the display should remain powered on while the system's awake.
329     */
330    kIOPMDriverAssertionPreventDisplaySleepBit      = 0x40,
331
332    /*! kIOPMDriverAssertionReservedBit7
333     * Reserved for storage family.
334     */
335    kIOPMDriverAssertionReservedBit7                = 0x80,
336
337    /*! kIOPMDriverAssertionMagicPacketWakeEnabledBit
338     * When set, driver is informing PM that magic packet wake is enabled.
339     */
340    kIOPMDriverAssertionMagicPacketWakeEnabledBit   = 0x100,
341
342    /*! kIOPMDriverAssertionNetworkKeepAliveActiveBit
343     * When set, driver is informing PM that it is holding the network
344     * interface up to do TCPKeepAlive
345     */
346    kIOPMDriverAssertionNetworkKeepAliveActiveBit   = 0x200
347};
348
349 /* kIOPMAssertionsDriverKey
350  * This kIOPMrootDomain key refers to a CFNumberRef property, containing
351  * a bitfield describing the aggregate PM assertion levels.
352  * Example: A value of 0 indicates that no driver has asserted anything.
353  * Or, a value of <link>kIOPMDriverAssertionCPUBit</link>
354  *   indicates that a driver (or drivers) have asserted a need for CPU and video.
355  */
356#define kIOPMAssertionsDriverKey            "DriverPMAssertions"
357
358 /* kIOPMAssertionsDriverKey
359  * This kIOPMrootDomain key refers to a CFNumberRef property, containing
360  * a bitfield describing the aggregate PM assertion levels.
361  * Example: A value of 0 indicates that no driver has asserted anything.
362  * Or, a value of <link>kIOPMDriverAssertionCPUBit</link>
363  *   indicates that a driver (or drivers) have asserted a need for CPU and video.
364  */
365#define kIOPMAssertionsDriverDetailedKey    "DriverPMAssertionsDetailed"
366
367/*******************************************************************************
368 *
369 * Kernel Driver assertion detailed dictionary keys
370 *
371 * Keys decode the Array & dictionary data structure under IOPMrootDomain property
372 *  kIOPMAssertionsDriverKey.
373 *
374 */
375#define kIOPMDriverAssertionIDKey               "ID"
376#define kIOPMDriverAssertionCreatedTimeKey      "CreatedTime"
377#define kIOPMDriverAssertionModifiedTimeKey     "ModifiedTime"
378#define kIOPMDriverAssertionOwnerStringKey      "Owner"
379#define kIOPMDriverAssertionOwnerServiceKey     "ServicePtr"
380#define kIOPMDriverAssertionRegistryEntryIDKey  "RegistryEntryID"
381#define kIOPMDriverAssertionLevelKey            "Level"
382#define kIOPMDriverAssertionAssertedKey         "Assertions"
383
384/*******************************************************************************
385 *
386 * Root Domain general interest messages
387 *
388 * Available by registering for interest type 'gIOGeneralInterest'
389 * on IOPMrootDomain.
390 *
391 ******************************************************************************/
392
393/* kIOPMMessageClamshellStateChange
394 * Delivered as a general interest notification on the IOPMrootDomain
395 * IOPMrootDomain sends this message when state of either AppleClamshellState
396 * or AppleClamshellCausesSleep changes. If this clamshell change results in
397 * a sleep, the sleep will initiate soon AFTER delivery of this message.
398 * The state of both variables is encoded in a bitfield argument sent with
399 * the message. Check bits 0 and 1 using kClamshellStateBit & kClamshellSleepBit
400 */
401enum {
402    kClamshellStateBit = (1 << 0),
403    kClamshellSleepBit = (1 << 1)
404};
405
406#define kIOPMMessageClamshellStateChange   \
407                iokit_family_msg(sub_iokit_powermanagement, 0x100)
408
409/* kIOPMMessageFeatureChange
410 * Delivered when the set of supported features ("Supported Features" dictionary
411 * under IOPMrootDomain registry) changes in some way. Typically addition or
412 * removal of a supported feature.
413 * RootDomain passes no argument with this message.
414 */
415#define kIOPMMessageFeatureChange           \
416                iokit_family_msg(sub_iokit_powermanagement, 0x110)
417
418/* kIOPMMessageInflowDisableCancelled
419 * The battery has drained completely to its "Fully Discharged" state.
420 * If a user process has disabled battery inflow for battery
421 * calibration, we forcibly re-enable Inflow at this point.
422 * If inflow HAS been forcibly re-enabled, bit 0
423 * (kInflowForciblyEnabledBit) will be set.
424 */
425enum {
426    kInflowForciblyEnabledBit = (1 << 0)
427};
428
429/* kIOPMMessageInternalBatteryFullyDischarged
430 * The battery has drained completely to its "Fully Discharged" state.
431 */
432#define kIOPMMessageInternalBatteryFullyDischarged  \
433                iokit_family_msg(sub_iokit_powermanagement, 0x120)
434
435/* kIOPMMessageSystemPowerEventOccurred
436 * Some major system thermal property has changed, and interested clients may
437 * modify their behavior.
438 */
439#define kIOPMMessageSystemPowerEventOccurred  \
440                iokit_family_msg(sub_iokit_powermanagement, 0x130)
441
442/* kIOPMMessageSleepWakeUUIDChange
443 * Either a new SleepWakeUUID has been specified at the beginning of a sleep,
444 * or we're removing the existing property upon completion of a wakeup.
445 */
446#define kIOPMMessageSleepWakeUUIDChange  \
447                iokit_family_msg(sub_iokit_powermanagement, 0x140)
448
449/* kIOPMMessageSleepWakeUUIDSet
450 * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when
451 * a new UUID has been specified.
452 */
453#define kIOPMMessageSleepWakeUUIDSet                    ((void *)1)
454
455/* kIOPMMessageSleepWakeUUIDCleared
456 * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when
457 * the current UUID has been removed.
458 */
459#define kIOPMMessageSleepWakeUUIDCleared                ((void *)0)
460
461/*! kIOPMMessageDriverAssertionsChanged
462 *  Sent when kernel PM driver assertions have changed.
463 */
464#define kIOPMMessageDriverAssertionsChanged  \
465                iokit_family_msg(sub_iokit_powermanagement, 0x150)
466
467/*! kIOPMMessageDarkWakeThermalEmergency
468 * Sent when machine becomes unsustainably warm in DarkWake.
469 * Kernel PM might choose to put the machine back to sleep right after.
470 */
471#define kIOPMMessageDarkWakeThermalEmergency \
472                iokit_family_msg(sub_iokit_powermanagement, 0x160)
473
474/*******************************************************************************
475 *
476 * Power commands issued to root domain
477 * Use with IOPMrootDomain::receivePowerNotification()
478 *
479 * These commands are issued from system drivers only:
480 *      ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily
481 *
482 * TODO: deprecate kIOPMAllowSleep and kIOPMPreventSleep
483 ******************************************************************************/
484enum {
485  kIOPMSleepNow                 = (1<<0),  // put machine to sleep now
486  kIOPMAllowSleep               = (1<<1),  // allow idle sleep
487  kIOPMPreventSleep             = (1<<2),  // do not allow idle sleep
488  kIOPMPowerButton              = (1<<3),  // power button was pressed
489  kIOPMClamshellClosed          = (1<<4),  // clamshell was closed
490  kIOPMPowerEmergency           = (1<<5),  // battery dangerously low
491  kIOPMDisableClamshell         = (1<<6),  // do not sleep on clamshell closure
492  kIOPMEnableClamshell          = (1<<7),  // sleep on clamshell closure
493  kIOPMProcessorSpeedChange     = (1<<8),  // change the processor speed
494  kIOPMOverTemp                 = (1<<9),  // system dangerously hot
495  kIOPMClamshellOpened          = (1<<10), // clamshell was opened
496  kIOPMDWOverTemp               = (1<<11)  // DarkWake thermal limits exceeded.
497};
498
499
500/*******************************************************************************
501 *
502 * Power Management Return Codes
503 *
504 ******************************************************************************/
505enum {
506    kIOPMNoErr                  = 0,
507
508    // Returned by driver's setPowerState(), powerStateWillChangeTo(),
509    // powerStateDidChangeTo(), or acknowledgeSetPowerState() to
510    // implicitly acknowledge power change upon function return.
511    kIOPMAckImplied             = 0,
512
513    // Deprecated
514    kIOPMWillAckLater           = 1,
515
516    // Returned by requestPowerDomainState() to indicate
517    // unrecognized specification parameter.
518    kIOPMBadSpecification       = 4,
519
520    // Returned by requestPowerDomainState() to indicate
521    // no power state matches search specification.
522    kIOPMNoSuchState            = 5,
523
524    // Deprecated
525    kIOPMCannotRaisePower       = 6,
526
527    // Deprecated
528    kIOPMParameterError         = 7,
529
530    // Returned when power management state is accessed
531    // before driver has called PMinit().
532    kIOPMNotYetInitialized      = 8,
533
534    // And the old constants; deprecated
535    IOPMNoErr = kIOPMNoErr,
536    IOPMAckImplied = kIOPMAckImplied,
537    IOPMWillAckLater = kIOPMWillAckLater,
538    IOPMBadSpecification = kIOPMBadSpecification,
539    IOPMNoSuchState = kIOPMNoSuchState,
540    IOPMCannotRaisePower = kIOPMCannotRaisePower,
541    IOPMParameterError = kIOPMParameterError,
542    IOPMNotYetInitialized = kIOPMNotYetInitialized
543};
544
545
546// IOPMPowerSource class descriptive strings
547// Power Source state is published as properties to the IORegistry under these
548// keys.
549#define kIOPMPSExternalConnectedKey                 "ExternalConnected"
550#define kIOPMPSExternalChargeCapableKey             "ExternalChargeCapable"
551#define kIOPMPSBatteryInstalledKey                  "BatteryInstalled"
552#define kIOPMPSIsChargingKey                        "IsCharging"
553#define kIOPMFullyChargedKey                        "FullyCharged"
554#define kIOPMPSAtWarnLevelKey                       "AtWarnLevel"
555#define kIOPMPSAtCriticalLevelKey                   "AtCriticalLevel"
556#define kIOPMPSCurrentCapacityKey                   "CurrentCapacity"
557#define kIOPMPSMaxCapacityKey                       "MaxCapacity"
558#define kIOPMPSDesignCapacityKey                    "DesignCapacity"
559#define kIOPMPSTimeRemainingKey                     "TimeRemaining"
560#define kIOPMPSAmperageKey                          "Amperage"
561#define kIOPMPSVoltageKey                           "Voltage"
562#define kIOPMPSCycleCountKey                        "CycleCount"
563#define kIOPMPSMaxErrKey                            "MaxErr"
564#define kIOPMPSAdapterInfoKey                       "AdapterInfo"
565#define kIOPMPSLocationKey                          "Location"
566#define kIOPMPSErrorConditionKey                    "ErrorCondition"
567#define kIOPMPSManufacturerKey                      "Manufacturer"
568#define kIOPMPSManufactureDateKey                   "ManufactureDate"
569#define kIOPMPSModelKey                             "Model"
570#define kIOPMPSSerialKey                            "Serial"
571#define kIOPMDeviceNameKey                          "DeviceName"
572#define kIOPMPSLegacyBatteryInfoKey                 "LegacyBatteryInfo"
573#define kIOPMPSBatteryHealthKey                     "BatteryHealth"
574#define kIOPMPSHealthConfidenceKey                  "HealthConfidence"
575#define kIOPMPSCapacityEstimatedKey	                "CapacityEstimated"
576#define kIOPMPSBatteryChargeStatusKey               "ChargeStatus"
577#define kIOPMPSBatteryTemperatureKey                "Temperature"
578#define kIOPMPSAdapterDetailsKey		    "AdapterDetails"
579#define kIOPMPSChargerConfigurationKey		    "ChargerConfiguration"
580
581// kIOPMPSBatteryChargeStatusKey may have one of the following values, or may have
582// no value. If kIOPMBatteryChargeStatusKey has a NULL value (or no value) associated with it
583// then charge is proceeding normally. If one of these battery charge status reasons is listed,
584// then the charge may have been interrupted.
585#define kIOPMBatteryChargeStatusTooHot              "HighTemperature"
586#define kIOPMBatteryChargeStatusTooCold             "LowTemperature"
587#define kIOPMBatteryChargeStatusTooHotOrCold	    "HighOrLowTemperature"
588#define kIOPMBatteryChargeStatusGradient            "BatteryTemperatureGradient"
589
590// Definitions for battery location, in case of multiple batteries.
591// A location of 0 is unspecified
592// Location is undefined for single battery systems
593enum {
594    kIOPMPSLocationLeft = 1001,
595    kIOPMPSLocationRight = 1002
596};
597
598// Battery quality health types, specified by BatteryHealth and HealthConfidence
599// properties in an IOPMPowerSource battery kext.
600enum {
601    kIOPMUndefinedValue = 0,
602    kIOPMPoorValue      = 1,
603    kIOPMFairValue      = 2,
604    kIOPMGoodValue      = 3
605};
606
607// Keys for kIOPMPSAdapterDetailsKey dictionary
608#define kIOPMPSAdapterDetailsIDKey		    "AdapterID"
609#define kIOPMPSAdapterDetailsWattsKey		    "Watts"
610#define kIOPMPSAdapterDetailsRevisionKey	    "AdapterRevision"
611#define kIOPMPSAdapterDetailsSerialNumberKey	    "SerialNumber"
612#define kIOPMPSAdapterDetailsFamilyKey		    "FamilyCode"
613#define kIOPMPSAdapterDetailsAmperageKey	    "Amperage"
614#define kIOPMPSAdapterDetailsDescriptionKey	    "Description"
615#define kIOPMPSAdapterDetailsPMUConfigurationKey    "PMUConfiguration"
616
617// Battery's time remaining estimate is invalid this long (seconds) after a wake
618#define kIOPMPSInvalidWakeSecondsKey           "BatteryInvalidWakeSeconds"
619
620// Battery must wait this long (seconds) after being completely charged before
621// the battery is settled.
622#define kIOPMPSPostChargeWaitSecondsKey        "PostChargeWaitSeconds"
623
624// Battery must wait this long (seconds) after being completely discharged
625// before the battery is settled.
626#define kIOPMPSPostDishargeWaitSecondsKey      "PostDischargeWaitSeconds"
627
628
629/* CPU Power Management status keys
630 * Pass as arguments to IOPMrootDomain::systemPowerEventOccurred
631 * Or as arguments to IOPMSystemPowerEventOccurred()
632 * Or to decode the dictionary obtained from IOPMCopyCPUPowerStatus()
633 * These keys reflect restrictions placed on the CPU by the system
634 * to bring the CPU's power consumption within allowable thermal and
635 * power constraints.
636 */
637
638
639/* kIOPMGraphicsPowerLimitsKey
640 *   The key representing the dictionary of graphics power limits.
641 *   The dictionary contains the other kIOPMCPUPower keys & their associated
642 *   values (e.g. Speed limit, Processor Count, and Schedule limits).
643 */
644#define kIOPMGraphicsPowerLimitsKey                     "Graphics_Power_Limits"
645
646/* kIOPMGraphicsPowerLimitPerformanceKey
647 *   The key representing the percent of overall performance made available
648 *   by the graphics chip as a percentage (integer 0 - 100).
649 */
650#define kIOPMGraphicsPowerLimitPerformanceKey           "Graphics_Power_Performance"
651
652
653
654/* kIOPMCPUPowerLimitsKey
655 *   The key representing the dictionary of CPU Power Limits.
656 *   The dictionary contains the other kIOPMCPUPower keys & their associated
657 *   values (e.g. Speed limit, Processor Count, and Schedule limits).
658 */
659#define kIOPMCPUPowerLimitsKey                          "CPU_Power_Limits"
660
661/* kIOPMCPUPowerLimitProcessorSpeedKey defines the speed & voltage limits placed
662 *   on the CPU.
663 *   Represented as a percentage (0-100) of maximum CPU speed.
664 */
665#define kIOPMCPUPowerLimitProcessorSpeedKey             "CPU_Speed_Limit"
666
667/* kIOPMCPUPowerLimitProcessorCountKey reflects how many, if any, CPUs have been
668 *   taken offline. Represented as an integer number of CPUs (0 - Max CPUs).
669 */
670#define kIOPMCPUPowerLimitProcessorCountKey             "CPU_Available_CPUs"
671
672/* kIOPMCPUPowerLimitSchedulerTimeKey represents the percentage (0-100) of CPU time
673 *   available. 100% at normal operation. The OS may limit this time for a percentage
674 *   less than 100%.
675 */
676#define kIOPMCPUPowerLimitSchedulerTimeKey              "CPU_Scheduler_Limit"
677
678
679/* Thermal Level Warning Key
680 * Indicates the thermal constraints placed on the system. This value may
681 * cause clients to action to consume fewer system resources.
682 * The value associated with this warning is defined by the platform.
683 */
684#define kIOPMThermalLevelWarningKey                     "Thermal_Level_Warning"
685
686/* Thermal Warning Level values
687 *      kIOPMThermalWarningLevelNormal - under normal operating conditions
688 *      kIOPMThermalWarningLevelDanger - thermal pressure may cause system slowdown
689 *      kIOPMThermalWarningLevelCrisis - thermal conditions may cause imminent shutdown
690 *
691 * The platform may define additional thermal levels if necessary.
692 */
693enum {
694  kIOPMThermalWarningLevelNormal    = 0,
695  kIOPMThermalWarningLevelDanger    = 5,
696  kIOPMThermalWarningLevelCrisis    = 10
697};
698
699
700// PM Settings Controller setting types
701// Settings types used primarily with:
702//      IOPMrootDomain::registerPMSettingController
703// The values are identical to the similarly named keys for use in user space
704// PM settings work. Those keys are defined in IOPMLibPrivate.h.
705#define kIOPMSettingWakeOnRingKey                   "Wake On Modem Ring"
706#define kIOPMSettingRestartOnPowerLossKey           "Automatic Restart On Power Loss"
707#define kIOPMSettingWakeOnACChangeKey               "Wake On AC Change"
708#define kIOPMSettingSleepOnPowerButtonKey           "Sleep On Power Button"
709#define kIOPMSettingWakeOnClamshellKey              "Wake On Clamshell Open"
710#define kIOPMSettingReduceBrightnessKey             "ReduceBrightness"
711#define kIOPMSettingDisplaySleepUsesDimKey          "Display Sleep Uses Dim"
712#define kIOPMSettingTimeZoneOffsetKey               "TimeZoneOffsetSeconds"
713#define kIOPMSettingMobileMotionModuleKey           "MobileMotionModule"
714#define kIOPMSettingGraphicsSwitchKey               "GPUSwitch"
715
716// Setting controlling drivers can register to receive scheduled wake data
717// Either in "CF seconds" type, or structured calendar data in a formatted
718// IOPMCalendarStruct defined below.
719#define kIOPMSettingAutoWakeSecondsKey              "wake"
720#define kIOPMSettingAutoWakeCalendarKey             "WakeByCalendarDate"
721#define kIOPMSettingAutoPowerSecondsKey             "poweron"
722#define kIOPMSettingAutoPowerCalendarKey            "PowerByCalendarDate"
723
724// Debug seconds auto wake
725// Used by sleep cycling debug tools
726#define kIOPMSettingDebugWakeRelativeKey            "WakeRelativeToSleep"
727#define kIOPMSettingDebugPowerRelativeKey           "PowerRelativeToShutdown"
728
729// Maintenance wake calendar.
730#define kIOPMSettingMaintenanceWakeCalendarKey      "MaintenanceWakeCalendarDate"
731
732
733struct IOPMCalendarStruct {
734    UInt32      year;
735    UInt8       month;
736    UInt8       day;
737    UInt8       hour;
738    UInt8       minute;
739    UInt8       second;
740    UInt8       selector;
741};
742typedef struct IOPMCalendarStruct IOPMCalendarStruct;
743
744// SetAggressiveness types
745enum {
746    kPMGeneralAggressiveness = 0,
747    kPMMinutesToDim,
748    kPMMinutesToSpinDown,
749    kPMMinutesToSleep,
750    kPMEthernetWakeOnLANSettings,
751    kPMSetProcessorSpeed,
752    kPMPowerSource,
753    kPMMotionSensor,
754    kPMLastAggressivenessType
755};
756#define kMaxType (kPMLastAggressivenessType-1)
757
758// SetAggressiveness values for the kPMPowerSource aggressiveness type
759enum {
760    kIOPMInternalPower = 1,
761    kIOPMExternalPower
762};
763
764#define kIOREMSleepEnabledKey               "REMSleepEnabled"
765
766// Strings for deciphering the dictionary returned from IOPMCopyBatteryInfo
767#define kIOBatteryInfoKey                   "IOBatteryInfo"
768#define kIOBatteryCurrentChargeKey          "Current"
769#define kIOBatteryCapacityKey               "Capacity"
770#define kIOBatteryFlagsKey                  "Flags"
771#define kIOBatteryVoltageKey                "Voltage"
772#define kIOBatteryAmperageKey               "Amperage"
773#define kIOBatteryCycleCountKey             "Cycle Count"
774
775enum {
776    kIOBatteryInstalled         = (1 << 2),
777    kIOBatteryCharge            = (1 << 1),
778    kIOBatteryChargerConnect    = (1 << 0)
779};
780
781// Private power management message indicating battery data has changed
782// Indicates new data resides in the IORegistry
783#define kIOPMMessageBatteryStatusHasChanged         iokit_family_msg(sub_iokit_pmu, 0x100)
784
785// Apple private Legacy messages for re-routing AutoWake and AutoPower messages to the PMU
786// through newer user space IOPMSchedulePowerEvent API
787#define kIOPMUMessageLegacyAutoWake                 iokit_family_msg(sub_iokit_pmu, 0x200)
788#define kIOPMUMessageLegacyAutoPower                iokit_family_msg(sub_iokit_pmu, 0x210)
789
790// For use with IOPMPowerSource bFlags
791#define IOPM_POWER_SOURCE_REV   2
792enum {
793  kIOPMACInstalled      = kIOBatteryChargerConnect,
794  kIOPMBatteryCharging  = kIOBatteryCharge,
795  kIOPMBatteryInstalled = kIOBatteryInstalled,
796  kIOPMUPSInstalled     = (1<<3),
797  kIOPMBatteryAtWarn    = (1<<4),
798  kIOPMBatteryDepleted  = (1<<5),
799  kIOPMACnoChargeCapability = (1<<6),     // AC adapter cannot charge battery
800  kIOPMRawLowBattery    = (1<<7),         // used only by  Platform Expert
801  kIOPMForceLowSpeed    = (1<<8),         // set by Platfm Expert, chk'd by Pwr Plugin
802  kIOPMClosedClamshell  = (1<<9),         // set by PMU - reflects state of the clamshell
803  kIOPMClamshellStateOnWake = (1<<10)     // used only by Platform Expert
804};
805
806// **********************************************
807// Internal power management data structures
808// **********************************************
809
810#if KERNEL && __cplusplus
811class IOService;
812
813enum {
814    kIOPowerEmergencyLevel = 1000
815};
816
817enum {
818    kIOPMSubclassPolicy,
819    kIOPMSuperclassPolicy1
820#ifdef KERNEL_PRIVATE
821    , kIOPMActivityTickleTypeAdvisory = 128
822#endif
823};
824
825struct stateChangeNote {
826    IOPMPowerFlags    stateFlags;
827    unsigned long    stateNum;
828    void *         powerRef;
829};
830typedef struct stateChangeNote stateChangeNote;
831
832#endif /* KERNEL && __cplusplus */
833struct IOPowerStateChangeNotification {
834    void *        powerRef;
835    unsigned long    returnValue;
836    unsigned long    stateNumber;
837    IOPMPowerFlags    stateFlags;
838};
839typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification;
840typedef IOPowerStateChangeNotification sleepWakeNote;
841
842/*! @struct IOPMSystemCapabilityChangeParameters
843    @abstract A structure describing a system capability change.
844    @discussion A system capability change is a system level transition from a set
845        of system capabilities to a new set of system capabilities. Power management
846        sends a <code>kIOMessageSystemCapabilityChange</code> message and provides
847        this structure as the message data (by reference) to
848        <code>gIOPriorityPowerStateInterest</code> clients when system capability
849        changes.
850    @field notifyRef An identifier for this message notification. Clients with pending
851        I/O can signal completion by calling <code>allowPowerChange()</code> with this
852        value as the argument. Clients that are able to process the notification
853        synchronously should ignore this field.
854    @field maxWaitForReply A return value to the caller indicating the maximum time in
855        microseconds to wait for the <code>allowPowerChange()</code> call. The default
856        value is zero, which indicates the client processing has finished, and power
857        management should not wait for an <code>allowPowerChange()</code> call.
858    @field changeFlags Flags will be set to indicate whether the notification precedes
859        the capability change (<code>kIOPMSystemCapabilityWillChange</code>), or after
860        the capability change has occurred (<code>kIOPMSystemCapabilityDidChange</code>).
861    @field __reserved1 Set to zero.
862    @field fromCapabilities The system capabilities at the start of the transition.
863    @field toCapabilities The system capabilities at the end of the transition.
864    @field __reserved2 Set to zero.
865 */
866struct IOPMSystemCapabilityChangeParameters {
867    uint32_t    notifyRef;
868    uint32_t    maxWaitForReply;
869    uint32_t    changeFlags;
870    uint32_t    __reserved1;
871    uint32_t    fromCapabilities;
872    uint32_t    toCapabilities;
873    uint32_t    __reserved2[4];
874};
875
876/*! @enum IOPMSystemCapabilityChangeFlags
877    @constant kIOPMSystemCapabilityWillChange Indicates the system capability will change.
878    @constant kIOPMSystemCapabilityDidChange Indicates the system capability has changed.
879*/
880enum {
881    kIOPMSystemCapabilityWillChange = 0x01,
882    kIOPMSystemCapabilityDidChange  = 0x02
883};
884
885enum {
886    kIOPMSystemCapabilityCPU        = 0x01,
887    kIOPMSystemCapabilityGraphics   = 0x02,
888    kIOPMSystemCapabilityAudio      = 0x04,
889    kIOPMSystemCapabilityNetwork    = 0x08
890};
891
892#endif /* ! _IOKIT_IOPM_H */
893