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