IOPM.h Reference

Declared in
IOPM.h

Overview

Defines power management constants and keys used by both in-kernel and user space power management.

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.

Most of the constants defined in IOPM.h are deprecated or for Apple internal use only, and are not elaborated on in headerdoc.

Included Headers

  • <IOKit/IOTypes.h>

  • <IOKit/IOMessage.h>

  • <IOKit/IOReturn.h>

Data Types

See the Overview section above for header-level documentation.

IOPMSystemCapabilityChangeParameters

A structure describing a system capability change.

struct IOPMSystemCapabilityChangeParameters {
   uint32_t notifyRef;
   uint32_t maxWaitForReply;
   uint32_t changeFlags;
   uint32_t __reserved1;
   uint32_t fromCapabilities;
   uint32_t toCapabilities;
   uint32_t __reserved2[4];
};
Fields
notifyRef

An identifier for this message notification. Clients with pending I/O can signal completion by calling allowPowerChange() with this value as the argument. Clients that are able to process the notification synchronously should ignore this field.

maxWaitForReply

A return value to the caller indicating the maximum time in microseconds to wait for the allowPowerChange() call. The default value is zero, which indicates the client processing has finished, and power management should not wait for an allowPowerChange() call.

changeFlags

Flags will be set to indicate whether the notification precedes the capability change (kIOPMSystemCapabilityWillChange), or after the capability change has occurred (kIOPMSystemCapabilityDidChange).

__reserved1

Set to zero.

fromCapabilities

The system capabilities at the start of the transition.

toCapabilities

The system capabilities at the end of the transition.

__reserved2

Set to zero.

Discussion

A system capability change is a system level transition from a set of system capabilities to a new set of system capabilities. Power management sends a kIOMessageSystemCapabilityChange message and provides this structure as the message data (by reference) to gIOPriorityPowerStateInterest clients when system capability changes.

Availability
  • Available in OS X v10.7 and later.
Declared In
IOPM.h

Constants

See the Overview section above for header-level documentation.

Miscellaneous Defines

   
#define kIOPMMessageDarkWakeThermalEmergency \
   iokit_family_msg(sub_iokit_powermanagement,
   0x160)
#define kIOPMMessageDriverAssertionsChanged \
   iokit_family_msg(sub_iokit_powermanagement,
   0x150)
Constants
kIOPMMessageDarkWakeThermalEmergency

kIOPMMessageDarkWakeThermalEmergency Sent when machine becomes unsustainably warm in DarkWake. Kernel PM might choose to put the machine back to sleep right after.

Available in OS X v10.8 and later.

Declared in IOPM.h.

kIOPMMessageDriverAssertionsChanged

kIOPMMessageDriverAssertionsChanged Sent when kernel PM driver assertions have changed.

Available in OS X v10.7 and later.

Declared in IOPM.h.

Global Variables

kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
kIOPMDriverAssertionCPUBit *= 0x01,  /! kIOPMDriverAssertionUSBExternalDeviceBit
   */
kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04,  /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit
   */
kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08,  /! kIOPMDriverAssertionExternalMediaMountedBit
   */
kIOPMDriverAssertionExternalMediaMountedBit *= 0x10,  /! kIOPMDriverAssertionReservedBit5
   */
kIOPMDriverAssertionReservedBit5 *= 0x20,  /! kIOPMDriverAssertionPreventDisplaySleepBit
   */
kIOPMDriverAssertionPreventDisplaySleepBit *= 0x40,  /! kIOPMDriverAssertionReservedBit7
   */
kIOPMDriverAssertionReservedBit7 *= 0x80,  /! kIOPMDriverAssertionMagicPacketWakeEnabledBit
   */
kIOPMDriverAssertionMagicPacketWakeEnabledBit *= 0x100,  /! kIOPMDriverAssertionNetworkKeepAliveActiveBit
   */
kIOPMDriverAssertionNetworkKeepAliveActiveBit = 0x200 };
Constants
kIOPMDriverAssertionCPUBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionExternalMediaMountedBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionMagicPacketWakeEnabledBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionNetworkKeepAliveActiveBit

kIOPMDriverAssertionNetworkKeepAliveActiveBit When set, driver is informing PM that it is holding the network interface up to do TCPKeepAlive

kIOPMDriverAssertionNetworkKeepAliveActiveBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionPreventDisplaySleepBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionReservedBit5

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionReservedBit7

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

kIOPMDriverAssertionUSBExternalDeviceBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

IOPMPowerFlags

Bits are used in defining capabilityFlags, inputPowerRequirements, and outputPowerCharacter in the IOPMPowerState structure.

enum {
   kIOPMPowerOn = 0x00000002,
   kIOPMDeviceUsable = 0x00008000,
   kIOPMLowPower = 0x00010000,
   kIOPMPreventIdleSleep = 0x00000040,
   kIOPMSleepCapability = 0x00000004,
   kIOPMRestartCapability = 0x00000080,
   kIOPMSleep = 0x00000001,
   kIOPMRestart = 0x00000080,
   kIOPMInitialDeviceState = 0x00000100,
   kIOPMRootDomainState = 0x00000200
};
   
typedef unsigned long IOPMPowerFlags;
Constants
kIOPMPowerOn

Indicates the device is on, requires power, and provides power. Useful as a: Capability, InputPowerRequirement, OutputPowerCharacter

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMDeviceUsable

Indicates the device is usable in this state. Useful only as a Capability

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMLowPower

Indicates device is in a low power state. May be bitwis-OR'd together with kIOPMDeviceUsable flag, to indicate the device is still usable.

A device with a capability of kIOPMLowPower may: Require either 0 or kIOPMPowerOn from its power parent Offer either kIOPMLowPower, kIOPMPowerOn, or 0 (no power at all) to its power plane children.

Useful only as a Capability, although USB drivers should consult USB family documentation for other valid circumstances to use the kIOPMLowPower bit.

Available in OS X v10.5 and later.

Declared in IOPM.h.

kIOPMPreventIdleSleep

In the capability field of a power state, disallows idle system sleep while the device is in that state.

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.

Useful only as a Capability.

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMSleepCapability

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.

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMRestartCapability

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.

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMSleep

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.

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMRestart

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.

Available in OS X v10.1 and later.

Declared in IOPM.h.

kIOPMInitialDeviceState

Indicates the initial power state for the device. If initialPowerStateForDomainState() returns a power state with this flag set in the capability field, then the initial power change is performed without calling the driver's setPowerState().

Available in OS X v10.7 and later.

Declared in IOPM.h.

kIOPMRootDomainState

An indication that the power flags represent the state of the root power domain. This bit must not be set in the IOPMPowerState structure. Power Management may pass this bit to initialPowerStateForDomainState() or powerStateForDomainState() to map from a global system state to the desired device state.

Available in OS X v10.9 and later.

Declared in IOPM.h.

Discussion

These bits may be bitwise-OR'd together in the IOPMPowerState capabilityFlags field, the outputPowerCharacter field, and/or the inputPowerRequirement field.

The comments clearly mark whether each flag should be used in the capabilityFlags field, outputPowerCharacter field, and inputPowerRequirement field, or all three.

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.

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.

IOPMSystemCapabilityChangeFlags

enum {
   kIOPMSystemCapabilityWillChange = 0x01,
   kIOPMSystemCapabilityDidChange = 0x02
};
Constants
kIOPMSystemCapabilityWillChange

Indicates the system capability will change.

Available in OS X v10.7 and later.

Declared in IOPM.h.

kIOPMSystemCapabilityDidChange

Indicates the system capability has changed.

Available in OS X v10.7 and later.

Declared in IOPM.h.