Mac Developer Library

Developer

IOPM.h Reference

Options
Deployment Target:

On This Page

IOPM.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

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.

  • A structure describing a system capability change.

    Declaration

    Objective-C

    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.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

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

    Constants

    • kIOPMMessageDarkWakeThermalEmergency

      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.

    • kIOPMMessageDriverAssertionsChanged

      kIOPMMessageDriverAssertionsChanged

      kIOPMMessageDriverAssertionsChanged Sent when kernel PM driver assertions have changed.

      Available in OS X v10.7 and later.

  • Declaration

    Objective-C

    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

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

    • kIOPMDriverAssertionExternalMediaMountedBit

      kIOPMDriverAssertionExternalMediaMountedBit

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

    • kIOPMDriverAssertionMagicPacketWakeEnabledBit

      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

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

    • kIOPMDriverAssertionNetworkKeepAliveActiveBit

      kIOPMDriverAssertionNetworkKeepAliveActiveBit

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

    • kIOPMDriverAssertionPreventDisplaySleepBit

      kIOPMDriverAssertionPreventDisplaySleepBit

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

    • kIOPMDriverAssertionReservedBit5

      kIOPMDriverAssertionReservedBit5

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

    • kIOPMDriverAssertionReservedBit7

      kIOPMDriverAssertionReservedBit7

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

    • kIOPMDriverAssertionUSBExternalDeviceBit

      kIOPMDriverAssertionUSBExternalDeviceBit

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

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

    Declaration

    Objective-C

    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

      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.

    • kIOPMDeviceUsable

      kIOPMDeviceUsable

      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.

    Import Statement

    Objective-C

    #include <IOPM.h>;

    Availability

    Available in OS X v10.0 and later.

  • Declaration

    Objective-C

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

    Constants

    • kIOPMSystemCapabilityWillChange

      kIOPMSystemCapabilityWillChange

      Indicates the system capability will change.

      Available in OS X v10.7 and later.

    • kIOPMSystemCapabilityDidChange

      kIOPMSystemCapabilityDidChange

      Indicates the system capability has changed.

      Available in OS X v10.7 and later.