X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/c0fea4742e91338fffdcf79f86a7c1d5e2b97eb1..d1ecb069dfe24481e4a83f44cb5217a2b06746d7:/iokit/IOKit/pwr_mgt/IOPM.h diff --git a/iokit/IOKit/pwr_mgt/IOPM.h b/iokit/IOKit/pwr_mgt/IOPM.h index 4d355012d..7d78225af 100644 --- a/iokit/IOKit/pwr_mgt/IOPM.h +++ b/iokit/IOKit/pwr_mgt/IOPM.h @@ -1,23 +1,29 @@ /* * Copyright (c) 1998-2005 Apple Computer, Inc. All rights reserved. * - * @APPLE_LICENSE_HEADER_START@ + * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * - * The contents of this file constitute Original Code as defined in and - * are subject to the Apple Public Source License Version 1.1 (the - * "License"). You may not use this file except in compliance with the - * License. Please obtain a copy of the License at - * http://www.apple.com/publicsource and read it before using this file. + * This file contains Original Code and/or Modifications of Original Code + * as defined in and that are subject to the Apple Public Source License + * Version 2.0 (the 'License'). You may not use this file except in + * compliance with the License. The rights granted to you under the License + * may not be used to create, or enable the creation or redistribution of, + * unlawful or unlicensed copies of an Apple operating system, or to + * circumvent, violate, or enable the circumvention or violation of, any + * terms of an Apple operating system software license agreement. * - * This Original Code and all software distributed under the License are - * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * Please obtain a copy of the License at + * http://www.opensource.apple.com/apsl/ and read it before using this file. + * + * The Original Code and all software distributed under the License are + * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the - * License for the specific language governing rights and limitations - * under the License. + * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. + * Please see the License for the specific language governing rights and + * limitations under the License. * - * @APPLE_LICENSE_HEADER_END@ + * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ #ifndef _IOKIT_IOPM_H #define _IOKIT_IOPM_H @@ -30,63 +36,115 @@ #include #endif +/*! @header IOPM.h + @abstract Defines power management constants and keys used by both in-kernel and user space power management. + @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. + Most of the constants defined in IOPM.h are deprecated or for Apple internal use only, and are not elaborated on in headerdoc. +*/ enum { kIOPMMaxPowerStates = 10, IOPMMaxPowerStates = kIOPMMaxPowerStates }; +/*! @enum IOPMPowerFlags + @abstract Bits are used in defining capabilityFlags, inputPowerRequirements, and outputPowerCharacter in the IOPMPowerState structure. + @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. + + @constant kIOPMPowerOn Indicates the device is on, requires power, and provides power. Useful as a: Capability, InputPowerRequirement, OutputPowerCharacter + + @constant kIOPMDeviceUsable Indicates the device is usable in this state. Useful only as a Capability + + @constant 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. + + @constant 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. + + @constant 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. + + @constant 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. + + @constant 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. + + @constant 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. +*/ typedef unsigned long IOPMPowerFlags; enum { - // The following bits are used in the input and output power fields. + kIOPMPowerOn = 0x00000002, + kIOPMDeviceUsable = 0x00008000, + kIOPMLowPower = 0x00010000, + kIOPMPreventIdleSleep = 0x00000040, + kIOPMSleepCapability = 0x00000004, + kIOPMRestartCapability = 0x00000080, + kIOPMSleep = 0x00000001, + kIOPMRestart = 0x00000080 +}; + +/* + * Private IOPMPowerFlags + * + * For Apple use only + * Not for use with non-Apple drivers + * Their behavior is undefined + */ +enum { kIOPMClockNormal = 0x0004, kIOPMClockRunning = 0x0008, - // Reserved - Used only between root and root parent. - kIOPMAuxPowerOn = 0x0020, - // Reserved - kIOPMPagingAvailable used only by now-defunct paging plexus - kIOPMPagingAvailable = 0x0020, - kIOPMPassThrough = 0x0100, - kIOPMDoze = 0x0400, - // Obsolete - use kIOPMDoze instead of kIOPMSoftSleep - kIOPMSoftSleep = 0x0400, - kIOPMSleep = 0x0001, - kIOPMRestart = 0x0080, - - // The following bits are used in the capabilites field and the power fields - kIOPMPowerOn = 0x0002, kIOPMPreventSystemSleep = 0x0010, - kIOPMPreventIdleSleep = 0x0040, - - // The following bits are used in the capabilites field only. - // Used between a driver and its policy-maker - kIOPMNotAttainable = 0x0001, - // Used internally in a power domain parent + kIOPMDoze = 0x0400, kIOPMChildClamp = 0x0080, - // Used internally in a power domain parent kIOPMChildClamp2 = 0x0200, - // Marks device as usable in this state - kIOPMDeviceUsable = 0x8000, - // Device runs at max performance in this state + kIOPMNotPowerManaged = 0x0800 +}; + + +/* + * Deprecated IOPMPowerFlags + * Their behavior is undefined when used in IOPMPowerState + * Capability, InputPowerRequirement, or OutputPowerCharacter fields. + */ +enum { kIOPMMaxPerformance = 0x4000, + kIOPMPassThrough = 0x0100, + kIOPMAuxPowerOn = 0x0020, + kIOPMNotAttainable = 0x0001, kIOPMContextRetained = 0x2000, kIOPMConfigRetained = 0x1000, - // Device is capable of system sleep in this state - kIOPMSleepCapability = 0x0004, - kIOPMRestartCapability = 0x0080, - - // Reserved - Error code. (this is an error return rather than a bit) - kIOPMNotPowerManaged = 0x0800, - // Therefore this bit safely overloads it kIOPMStaticPowerValid = 0x0800, - + kIOPMSoftSleep = 0x0400, kIOPMCapabilitiesMask = kIOPMPowerOn | kIOPMDeviceUsable | kIOPMMaxPerformance | kIOPMContextRetained | kIOPMConfigRetained | kIOPMSleepCapability | kIOPMRestartCapability }; - +/* + * Support for old names of IOPMPowerFlag constants + */ enum { IOPMNotAttainable = kIOPMNotAttainable, IOPMPowerOn = kIOPMPowerOn, @@ -98,7 +156,6 @@ enum { IOPMContextRetained = kIOPMContextRetained, IOPMConfigRetained = kIOPMConfigRetained, IOPMNotPowerManaged = kIOPMNotPowerManaged, - IOPMPagingAvailable = kIOPMPagingAvailable, IOPMSoftSleep = kIOPMSoftSleep }; @@ -153,10 +210,26 @@ enum { */ #define kAppleClamshellCausesSleepKey "AppleClamshellCausesSleep" +/* kIOPMSleepWakeUUIDKey + * Key refers to a CFStringRef that will uniquely identify + * a sleep/wake cycle for logging & tracking. + * The key becomes valid at the beginning of a sleep cycle - before we + * initiate any sleep/wake notifications. + * The key becomes invalid at the completion of a system wakeup. The + * property will not be present in the IOPMrootDomain's registry entry + * when it is invalid. + * + * See IOPMrootDomain notification kIOPMMessageSleepWakeUUIDChange + */ + #define kIOPMSleepWakeUUIDKey "SleepWakeUUID" + /******************************************************************************* * * Root Domain general interest messages * + * Available by registering for interest type 'gIOGeneralInterest' + * on IOPMrootDomain. + * ******************************************************************************/ /* kIOPMMessageClamshellStateChange @@ -195,13 +268,42 @@ enum { kInflowForciblyEnabledBit = (1 << 0) }; +/* kIOPMMessageInternalBatteryFullyDischarged + * The battery has drained completely to its "Fully Discharged" state. + */ #define kIOPMMessageInternalBatteryFullyDischarged \ iokit_family_msg(sub_iokit_powermanagement, 0x120) +/* kIOPMMessageSystemPowerEventOccurred + * Some major system thermal property has changed, and interested clients may + * modify their behavior. + */ +#define kIOPMMessageSystemPowerEventOccurred \ + iokit_family_msg(sub_iokit_powermanagement, 0x130) + +/* kIOPMMessageSleepWakeUUIDChange + * Either a new SleepWakeUUID has been specified at the beginning of a sleep, + * or we're removing the existing property upon completion of a wakeup. + */ +#define kIOPMMessageSleepWakeUUIDChange \ + iokit_family_msg(sub_iokit_powermanagement, 0x140) + +/* kIOPMMessageSleepWakeUUIDSet + * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when + * a new UUID has been specified. + */ +#define kIOPMMessageSleepWakeUUIDSet ((void *)1) + +/* kIOPMMessageSleepWakeUUIDCleared + * Argument accompanying the kIOPMMessageSleepWakeUUIDChange notification when + * the current UUID has been removed. + */ +#define kIOPMMessageSleepWakeUUIDCleared ((void *)0) /******************************************************************************* * * Power commands issued to root domain + * Use with IOPMrootDomain::receivePowerNotification() * * These commands are issued from system drivers only: * ApplePMU, AppleSMU, IOGraphics, AppleACPIFamily @@ -221,6 +323,7 @@ enum { kIOPMClamshellOpened = (1<<10) // clamshell was opened }; + /******************************************************************************* * * Power Management Return Codes @@ -228,25 +331,31 @@ enum { ******************************************************************************/ enum { kIOPMNoErr = 0, - // Returned by powerStateWillChange and powerStateDidChange: - // Immediate acknowledgement of power state change + + // Returned by driver's setPowerState(), powerStateWillChangeTo(), + // powerStateDidChangeTo(), or acknowledgeSetPowerState() to + // implicitly acknowledge power change upon function return. kIOPMAckImplied = 0, - // Acknowledgement of power state change will come later + + // Deprecated kIOPMWillAckLater = 1, - - // Returned by requestDomainState: - // Unrecognized specification parameter + + // Returned by requestPowerDomainState() to indicate + // unrecognized specification parameter. kIOPMBadSpecification = 4, - // No power state matches search specification + + // Returned by requestPowerDomainState() to indicate + // no power state matches search specification. kIOPMNoSuchState = 5, - - // Device cannot change its power for some reason + + // Deprecated kIOPMCannotRaisePower = 6, - - // Returned by changeStateTo: - // Requested state doesn't exist + + // Deprecated kIOPMParameterError = 7, - // Device not yet fully hooked into power management + + // Returned when power management state is accessed + // before driver has called PMinit(). kIOPMNotYetInitialized = 8, // And the old constants; deprecated @@ -290,6 +399,17 @@ enum { #define kIOPMPSLegacyBatteryInfoKey "LegacyBatteryInfo" #define kIOPMPSBatteryHealthKey "BatteryHealth" #define kIOPMPSHealthConfidenceKey "HealthConfidence" +#define kIOPMPSCapacityEstimatedKey "CapacityEstimated" +#define kIOPMPSBatteryChargeStatusKey "ChargeStatus" +#define kIOPMPSBatteryTemperatureKey "Temperature" + +// kIOPMPSBatteryChargeStatusKey may have one of the following values, or may have +// no value. If kIOPMBatteryChargeStatusKey has a NULL value (or no value) associated with it +// then charge is proceeding normally. If one of these battery charge status reasons is listed, +// then the charge may have been interrupted. +#define kIOPMBatteryChargeStatusTooHot "HighTemperature" +#define kIOPMBatteryChargeStatusTooCold "LowTemperature" +#define kIOPMBatteryChargeStatusGradient "BatteryTemperatureGradient" // Definitions for battery location, in case of multiple batteries. // A location of 0 is unspecified @@ -320,6 +440,76 @@ enum { #define kIOPMPSPostDishargeWaitSecondsKey "PostDischargeWaitSeconds" +/* CPU Power Management status keys + * Pass as arguments to IOPMrootDomain::systemPowerEventOccurred + * Or as arguments to IOPMSystemPowerEventOccurred() + * Or to decode the dictionary obtained from IOPMCopyCPUPowerStatus() + * These keys reflect restrictions placed on the CPU by the system + * to bring the CPU's power consumption within allowable thermal and + * power constraints. + */ + + +/* kIOPMGraphicsPowerLimitsKey + * The key representing the dictionary of graphics power limits. + * The dictionary contains the other kIOPMCPUPower keys & their associated + * values (e.g. Speed limit, Processor Count, and Schedule limits). + */ +#define kIOPMGraphicsPowerLimitsKey "Graphics_Power_Limits" + +/* kIOPMGraphicsPowerLimitPerformanceKey + * The key representing the percent of overall performance made available + * by the graphics chip as a percentage (integer 0 - 100). + */ +#define kIOPMGraphicsPowerLimitPerformanceKey "Graphics_Power_Performance" + + + +/* kIOPMCPUPowerLimitsKey + * The key representing the dictionary of CPU Power Limits. + * The dictionary contains the other kIOPMCPUPower keys & their associated + * values (e.g. Speed limit, Processor Count, and Schedule limits). + */ +#define kIOPMCPUPowerLimitsKey "CPU_Power_Limits" + +/* kIOPMCPUPowerLimitProcessorSpeedKey defines the speed & voltage limits placed + * on the CPU. + * Represented as a percentage (0-100) of maximum CPU speed. + */ +#define kIOPMCPUPowerLimitProcessorSpeedKey "CPU_Speed_Limit" + +/* kIOPMCPUPowerLimitProcessorCountKey reflects how many, if any, CPUs have been + * taken offline. Represented as an integer number of CPUs (0 - Max CPUs). + */ +#define kIOPMCPUPowerLimitProcessorCountKey "CPU_Available_CPUs" + +/* kIOPMCPUPowerLimitSchedulerTimeKey represents the percentage (0-100) of CPU time + * available. 100% at normal operation. The OS may limit this time for a percentage + * less than 100%. + */ +#define kIOPMCPUPowerLimitSchedulerTimeKey "CPU_Scheduler_Limit" + + +/* Thermal Level Warning Key + * Indicates the thermal constraints placed on the system. This value may + * cause clients to action to consume fewer system resources. + * The value associated with this warning is defined by the platform. + */ +#define kIOPMThermalLevelWarningKey "Thermal_Level_Warning" + +/* Thermal Warning Level values + * kIOPMThermalWarningLevelNormal - under normal operating conditions + * kIOPMThermalWarningLevelDanger - thermal pressure may cause system slowdown + * kIOPMThermalWarningLevelCrisis - thermal conditions may cause imminent shutdown + * + * The platform may define additional thermal levels if necessary. + */ +enum { + kIOPMThermalWarningLevelNormal = 0, + kIOPMThermalWarningLevelDanger = 5, + kIOPMThermalWarningLevelCrisis = 10 +}; + // PM Settings Controller setting types // Settings types used primarily with: @@ -334,6 +524,8 @@ enum { #define kIOPMSettingReduceBrightnessKey "ReduceBrightness" #define kIOPMSettingDisplaySleepUsesDimKey "Display Sleep Uses Dim" #define kIOPMSettingTimeZoneOffsetKey "TimeZoneOffsetSeconds" +#define kIOPMSettingMobileMotionModuleKey "MobileMotionModule" +#define kIOPMSettingGraphicsSwitchKey "GPUSwitch" // Setting controlling drivers can register to receive scheduled wake data // Either in "CF seconds" type, or structured calendar data in a formatted @@ -348,6 +540,9 @@ enum { #define kIOPMSettingDebugWakeRelativeKey "WakeRelativeToSleep" #define kIOPMSettingDebugPowerRelativeKey "PowerRelativeToShutdown" +// Maintenance wake calendar. +#define kIOPMSettingMaintenanceWakeCalendarKey "MaintenanceWakeCalendarDate" + struct IOPMCalendarStruct { UInt32 year; UInt8 month; @@ -453,8 +648,6 @@ struct IOPowerStateChangeNotification { }; typedef struct IOPowerStateChangeNotification IOPowerStateChangeNotification; typedef IOPowerStateChangeNotification sleepWakeNote; - -extern void IOPMRegisterDevice(const char *, IOService *); #endif /* KERNEL && __cplusplus */ #endif /* ! _IOKIT_IOPM_H */