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