IOPM.h Reference

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.

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.

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

Available in OS X v10.1 and later.

kIOPMLowPower

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.

kIOPMPreventIdleSleep

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.

kIOPMSleepCapability

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.

kIOPMRestartCapability

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.

kIOPMSleep

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.

kIOPMRestart

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.

kIOPMInitialDeviceState

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.

kIOPMRootDomainState

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.

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.