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