/*++ BUILD Version: 0001 // Increment this if a change has global effects
Copyright (c) Microsoft Corporation. All rights reserved.
Module Name:
ntpoapi.h
Abstract:
This module contains the user APIs for the NT Power Management.
Author:
Revision History:
--*/
#ifndef _NTPOAPI_
#define _NTPOAPI_
#if _MSC_VER > 1000
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
//
// Power Management user APIs
//
// begin_ntddk begin_ntifs begin_nthal begin_ntminiport begin_wdm
#ifndef _PO_DDK_
#define _PO_DDK_
// begin_winnt
typedef enum _SYSTEM_POWER_STATE {
PowerSystemUnspecified = 0,
PowerSystemWorking = 1,
PowerSystemSleeping1 = 2,
PowerSystemSleeping2 = 3,
PowerSystemSleeping3 = 4,
PowerSystemHibernate = 5,
PowerSystemShutdown = 6,
PowerSystemMaximum = 7
} SYSTEM_POWER_STATE, *PSYSTEM_POWER_STATE;
#define POWER_SYSTEM_MAXIMUM 7
typedef enum {
PowerActionNone = 0,
PowerActionReserved,
PowerActionSleep,
PowerActionHibernate,
PowerActionShutdown,
PowerActionShutdownReset,
PowerActionShutdownOff,
PowerActionWarmEject
} POWER_ACTION, *PPOWER_ACTION;
typedef enum _DEVICE_POWER_STATE {
PowerDeviceUnspecified = 0,
PowerDeviceD0,
PowerDeviceD1,
PowerDeviceD2,
PowerDeviceD3,
PowerDeviceMaximum
} DEVICE_POWER_STATE, *PDEVICE_POWER_STATE;
// end_winnt
typedef union _POWER_STATE {
SYSTEM_POWER_STATE SystemState;
DEVICE_POWER_STATE DeviceState;
} POWER_STATE, *PPOWER_STATE;
typedef enum _POWER_STATE_TYPE {
SystemPowerState = 0,
DevicePowerState
} POWER_STATE_TYPE, *PPOWER_STATE_TYPE;
//
// Generic power related IOCTLs
//
#define IOCTL_QUERY_DEVICE_POWER_STATE \
CTL_CODE(FILE_DEVICE_BATTERY, 0x0, METHOD_BUFFERED, FILE_READ_ACCESS)
#define IOCTL_SET_DEVICE_WAKE \
CTL_CODE(FILE_DEVICE_BATTERY, 0x1, METHOD_BUFFERED, FILE_WRITE_ACCESS)
#define IOCTL_CANCEL_DEVICE_WAKE \
CTL_CODE(FILE_DEVICE_BATTERY, 0x2, METHOD_BUFFERED, FILE_WRITE_ACCESS)
//
// Defines for W32 interfaces
//
// begin_winnt
#define ES_SYSTEM_REQUIRED ((ULONG)0x00000001)
#define ES_DISPLAY_REQUIRED ((ULONG)0x00000002)
#define ES_USER_PRESENT ((ULONG)0x00000004)
#define ES_CONTINUOUS ((ULONG)0x80000000)
typedef ULONG EXECUTION_STATE;
typedef enum {
LT_DONT_CARE,
LT_LOWEST_LATENCY
} LATENCY_TIME;
// end_ntminiport end_ntifs end_wdm end_ntddk
//-----------------------------------------------------------------------------
// Device Power Information
// Accessable via CM_Get_DevInst_Registry_Property_Ex(CM_DRP_DEVICE_POWER_DATA)
//-----------------------------------------------------------------------------
#define PDCAP_D0_SUPPORTED 0x00000001
#define PDCAP_D1_SUPPORTED 0x00000002
#define PDCAP_D2_SUPPORTED 0x00000004
#define PDCAP_D3_SUPPORTED 0x00000008
#define PDCAP_WAKE_FROM_D0_SUPPORTED 0x00000010
#define PDCAP_WAKE_FROM_D1_SUPPORTED 0x00000020
#define PDCAP_WAKE_FROM_D2_SUPPORTED 0x00000040
#define PDCAP_WAKE_FROM_D3_SUPPORTED 0x00000080
#define PDCAP_WARM_EJECT_SUPPORTED 0x00000100
typedef struct CM_Power_Data_s {
ULONG PD_Size;
DEVICE_POWER_STATE PD_MostRecentPowerState;
ULONG PD_Capabilities;
ULONG PD_D1Latency;
ULONG PD_D2Latency;
ULONG PD_D3Latency;
DEVICE_POWER_STATE PD_PowerStateMapping[POWER_SYSTEM_MAXIMUM];
SYSTEM_POWER_STATE PD_DeepestSystemWake;
} CM_POWER_DATA, *PCM_POWER_DATA;
// begin_ntddk
typedef enum {
SystemPowerPolicyAc,
SystemPowerPolicyDc,
VerifySystemPolicyAc,
VerifySystemPolicyDc,
SystemPowerCapabilities,
SystemBatteryState,
SystemPowerStateHandler,
ProcessorStateHandler,
SystemPowerPolicyCurrent,
AdministratorPowerPolicy,
SystemReserveHiberFile,
ProcessorInformation,
SystemPowerInformation,
ProcessorStateHandler2,
LastWakeTime, // Compare with KeQueryInterruptTime()
LastSleepTime, // Compare with KeQueryInterruptTime()
SystemExecutionState,
SystemPowerStateNotifyHandler,
ProcessorPowerPolicyAc,
ProcessorPowerPolicyDc,
VerifyProcessorPowerPolicyAc,
VerifyProcessorPowerPolicyDc,
ProcessorPowerPolicyCurrent
} POWER_INFORMATION_LEVEL;
// begin_wdm
//
// System power manager capabilities
//
typedef struct {
ULONG Granularity;
ULONG Capacity;
} BATTERY_REPORTING_SCALE, *PBATTERY_REPORTING_SCALE;
// end_winnt
// begin_ntminiport
// begin_ntifs
#endif // !_PO_DDK_
// end_ntddk end_ntminiport end_wdm end_ntifs
#define POWER_PERF_SCALE 100
#define PERF_LEVEL_TO_PERCENT(_x_) ((_x_ * 1000) / (POWER_PERF_SCALE * 10))
#define PERCENT_TO_PERF_LEVEL(_x_) ((_x_ * POWER_PERF_SCALE * 10) / 1000)
//
// Policy manager state handler interfaces
//
// power state handlers
typedef enum {
PowerStateSleeping1,
PowerStateSleeping2,
PowerStateSleeping3,
PowerStateSleeping4,
PowerStateSleeping4Firmware,
PowerStateShutdownReset,
PowerStateShutdownOff,
PowerStateMaximum
} POWER_STATE_HANDLER_TYPE, *PPOWER_STATE_HANDLER_TYPE;
typedef
NTSTATUS
(*PENTER_STATE_SYSTEM_HANDLER)(
IN PVOID SystemContext
);
typedef
NTSTATUS
(*PENTER_STATE_HANDLER)(
IN PVOID Context,
IN PENTER_STATE_SYSTEM_HANDLER SystemHandler OPTIONAL,
IN PVOID SystemContext,
IN LONG NumberProcessors,
IN volatile PLONG Number
);
typedef struct {
POWER_STATE_HANDLER_TYPE Type;
BOOLEAN RtcWake;
UCHAR Spare[3];
PENTER_STATE_HANDLER Handler;
PVOID Context;
} POWER_STATE_HANDLER, *PPOWER_STATE_HANDLER;
typedef
NTSTATUS
(*PENTER_STATE_NOTIFY_HANDLER)(
IN POWER_STATE_HANDLER_TYPE State,
IN PVOID Context,
IN BOOLEAN Entering
);
typedef struct {
PENTER_STATE_NOTIFY_HANDLER Handler;
PVOID Context;
} POWER_STATE_NOTIFY_HANDLER, *PPOWER_STATE_NOTIFY_HANDLER;
NTSYSCALLAPI
NTSTATUS
NTAPI
NtPowerInformation(
IN POWER_INFORMATION_LEVEL InformationLevel,
IN PVOID InputBuffer OPTIONAL,
IN ULONG InputBufferLength,
OUT PVOID OutputBuffer OPTIONAL,
IN ULONG OutputBufferLength
);
// processor idle functions
typedef struct {
ULONGLONG StartTime;
ULONGLONG EndTime;
ULONG IdleHandlerReserved[4];
} PROCESSOR_IDLE_TIMES, *PPROCESSOR_IDLE_TIMES;
typedef
BOOLEAN
(FASTCALL *PPROCESSOR_IDLE_HANDLER) (
IN OUT PPROCESSOR_IDLE_TIMES IdleTimes
);
typedef struct {
ULONG HardwareLatency;
PPROCESSOR_IDLE_HANDLER Handler;
} PROCESSOR_IDLE_HANDLER_INFO, *PPROCESSOR_IDLE_HANDLER_INFO;
typedef
VOID
(FASTCALL *PSET_PROCESSOR_THROTTLE) (
IN UCHAR Throttle
);
typedef
NTSTATUS
(FASTCALL *PSET_PROCESSOR_THROTTLE2) (
IN UCHAR Throttle
);
#define MAX_IDLE_HANDLERS 3
typedef struct {
UCHAR ThrottleScale;
BOOLEAN ThrottleOnIdle;
PSET_PROCESSOR_THROTTLE SetThrottle;
ULONG NumIdleHandlers;
PROCESSOR_IDLE_HANDLER_INFO IdleHandler[MAX_IDLE_HANDLERS];
} PROCESSOR_STATE_HANDLER, *PPROCESSOR_STATE_HANDLER;
// Processor_Perf_Level Flags
#define PROCESSOR_STATE_TYPE_PERFORMANCE 0x1
#define PROCESSOR_STATE_TYPE_THROTTLE 0x2
typedef struct {
UCHAR PercentFrequency; // max == POWER_PERF_SCALE
UCHAR Reserved;
USHORT Flags;
} PROCESSOR_PERF_LEVEL, *PPROCESSOR_PERF_LEVEL;
typedef struct {
UCHAR PercentFrequency; // max == POWER_PERF_SCALE
UCHAR MinCapacity; // battery capacity %
USHORT Power; // in milliwatts
UCHAR IncreaseLevel; // goto higher state
UCHAR DecreaseLevel; // goto lower state
USHORT Flags;
ULONG IncreaseTime; // in tick counts
ULONG DecreaseTime; // in tick counts
ULONG IncreaseCount; // goto higher state
ULONG DecreaseCount; // goto lower state
ULONGLONG PerformanceTime; // Tick count
} PROCESSOR_PERF_STATE, *PPROCESSOR_PERF_STATE;
typedef struct {
ULONG NumIdleHandlers;
PROCESSOR_IDLE_HANDLER_INFO IdleHandler[MAX_IDLE_HANDLERS];
PSET_PROCESSOR_THROTTLE2 SetPerfLevel;
ULONG HardwareLatency;
UCHAR NumPerfStates;
PROCESSOR_PERF_LEVEL PerfLevel[1]; // variable size
} PROCESSOR_STATE_HANDLER2, *PPROCESSOR_STATE_HANDLER2;
// begin_winnt
//
// Power Policy Management interfaces
//
typedef struct {
POWER_ACTION Action;
ULONG Flags;
ULONG EventCode;
} POWER_ACTION_POLICY, *PPOWER_ACTION_POLICY;
// POWER_ACTION_POLICY->Flags:
#define POWER_ACTION_QUERY_ALLOWED 0x00000001
#define POWER_ACTION_UI_ALLOWED 0x00000002
#define POWER_ACTION_OVERRIDE_APPS 0x00000004
#define POWER_ACTION_LIGHTEST_FIRST 0x10000000
#define POWER_ACTION_LOCK_CONSOLE 0x20000000
#define POWER_ACTION_DISABLE_WAKES 0x40000000
#define POWER_ACTION_CRITICAL 0x80000000
// POWER_ACTION_POLICY->EventCode flags
#define POWER_LEVEL_USER_NOTIFY_TEXT 0x00000001
#define POWER_LEVEL_USER_NOTIFY_SOUND 0x00000002
#define POWER_LEVEL_USER_NOTIFY_EXEC 0x00000004
#define POWER_USER_NOTIFY_BUTTON 0x00000008
#define POWER_USER_NOTIFY_SHUTDOWN 0x00000010
#define POWER_FORCE_TRIGGER_RESET 0x80000000
// system battery drain policies
typedef struct {
BOOLEAN Enable;
UCHAR Spare[3];
ULONG BatteryLevel;
POWER_ACTION_POLICY PowerPolicy;
SYSTEM_POWER_STATE MinSystemState;
} SYSTEM_POWER_LEVEL, *PSYSTEM_POWER_LEVEL;
// Discharge policy constants
#define NUM_DISCHARGE_POLICIES 4
#define DISCHARGE_POLICY_CRITICAL 0
#define DISCHARGE_POLICY_LOW 1
//
// Throttling policies
//
#define PO_THROTTLE_NONE 0
#define PO_THROTTLE_CONSTANT 1
#define PO_THROTTLE_DEGRADE 2
#define PO_THROTTLE_ADAPTIVE 3
#define PO_THROTTLE_MAXIMUM 4 // not a policy, just a limit
// system power policies
typedef struct _SYSTEM_POWER_POLICY {
ULONG Revision; // 1
// events
POWER_ACTION_POLICY PowerButton;
POWER_ACTION_POLICY SleepButton;
POWER_ACTION_POLICY LidClose;
SYSTEM_POWER_STATE LidOpenWake;
ULONG Reserved;
// "system idle" detection
POWER_ACTION_POLICY Idle;
ULONG IdleTimeout;
UCHAR IdleSensitivity;
// dynamic throttling policy
// PO_THROTTLE_NONE, PO_THROTTLE_CONSTANT, PO_THROTTLE_DEGRADE, or PO_THROTTLE_ADAPTIVE
UCHAR DynamicThrottle;
UCHAR Spare2[2];
// meaning of power action "sleep"
SYSTEM_POWER_STATE MinSleep;
SYSTEM_POWER_STATE MaxSleep;
SYSTEM_POWER_STATE ReducedLatencySleep;
ULONG WinLogonFlags;
// parameters for dozing
ULONG Spare3;
ULONG DozeS4Timeout;
// battery policies
ULONG BroadcastCapacityResolution;
SYSTEM_POWER_LEVEL DischargePolicy[NUM_DISCHARGE_POLICIES];
// video policies
ULONG VideoTimeout;
BOOLEAN VideoDimDisplay;
ULONG VideoReserved[3];
// hard disk policies
ULONG SpindownTimeout;
// processor policies
BOOLEAN OptimizeForPower;
UCHAR FanThrottleTolerance;
UCHAR ForcedThrottle;
UCHAR MinThrottle;
POWER_ACTION_POLICY OverThrottled;
} SYSTEM_POWER_POLICY, *PSYSTEM_POWER_POLICY;
// processor power policy state
typedef struct _PROCESSOR_POWER_POLICY_INFO {
// Time based information (will be converted to kernel units)
ULONG TimeCheck; // in US
ULONG DemoteLimit; // in US
ULONG PromoteLimit; // in US
// Percentage based information
UCHAR DemotePercent;
UCHAR PromotePercent;
UCHAR Spare[2];
// Flags
ULONG AllowDemotion:1;
ULONG AllowPromotion:1;
ULONG Reserved:30;
} PROCESSOR_POWER_POLICY_INFO, *PPROCESSOR_POWER_POLICY_INFO;
// processor power policy
typedef struct _PROCESSOR_POWER_POLICY {
ULONG Revision; // 1
// Dynamic Throttling Policy
UCHAR DynamicThrottle;
UCHAR Spare[3];
// Flags
ULONG Reserved;
// System policy information
// The Array is last, in case it needs to be grown and the structure
// revision incremented.
ULONG PolicyCount;
PROCESSOR_POWER_POLICY_INFO Policy[3];
} PROCESSOR_POWER_POLICY, *PPROCESSOR_POWER_POLICY;
// administrator power policy overrides
typedef struct _ADMINISTRATOR_POWER_POLICY {
// meaning of power action "sleep"
SYSTEM_POWER_STATE MinSleep;
SYSTEM_POWER_STATE MaxSleep;
// video policies
ULONG MinVideoTimeout;
ULONG MaxVideoTimeout;
// disk policies
ULONG MinSpindownTimeout;
ULONG MaxSpindownTimeout;
} ADMINISTRATOR_POWER_POLICY, *PADMINISTRATOR_POWER_POLICY;
// end_winnt
NTSYSCALLAPI
NTSTATUS
NTAPI
NtSetThreadExecutionState(
IN EXECUTION_STATE esFlags, // ES_xxx flags
OUT EXECUTION_STATE *PreviousFlags
);
NTSYSCALLAPI
NTSTATUS
NTAPI
NtRequestWakeupLatency(
IN LATENCY_TIME latency
);
NTSYSCALLAPI
NTSTATUS
NTAPI
NtInitiatePowerAction(
IN POWER_ACTION SystemAction,
IN SYSTEM_POWER_STATE MinSystemState,
IN ULONG Flags, // POWER_ACTION_xxx flags
IN BOOLEAN Asynchronous
);
NTSYSCALLAPI // only called by WinLogon
NTSTATUS
NTAPI
NtSetSystemPowerState(
IN POWER_ACTION SystemAction,
IN SYSTEM_POWER_STATE MinSystemState,
IN ULONG Flags // POWER_ACTION_xxx flags
);
NTSYSCALLAPI
NTSTATUS
NTAPI
NtGetDevicePowerState(
IN HANDLE Device,
OUT DEVICE_POWER_STATE *State
);
NTSYSCALLAPI
NTSTATUS
NTAPI
NtCancelDeviceWakeupRequest(
IN HANDLE Device
);
NTSYSCALLAPI
BOOLEAN
NTAPI
NtIsSystemResumeAutomatic(
VOID
);
NTSYSCALLAPI
NTSTATUS
NTAPI
NtRequestDeviceWakeup(
IN HANDLE Device
);
// WinLogonFlags:
#define WINLOGON_LOCK_ON_SLEEP 0x00000001
// begin_winnt
typedef struct {
// Misc supported system features
BOOLEAN PowerButtonPresent;
BOOLEAN SleepButtonPresent;
BOOLEAN LidPresent;
BOOLEAN SystemS1;
BOOLEAN SystemS2;
BOOLEAN SystemS3;
BOOLEAN SystemS4; // hibernate
BOOLEAN SystemS5; // off
BOOLEAN HiberFilePresent;
BOOLEAN FullWake;
BOOLEAN VideoDimPresent;
BOOLEAN ApmPresent;
BOOLEAN UpsPresent;
// Processors
BOOLEAN ThermalControl;
BOOLEAN ProcessorThrottle;
UCHAR ProcessorMinThrottle;
UCHAR ProcessorMaxThrottle;
UCHAR spare2[4];
// Disk
BOOLEAN DiskSpinDown;
UCHAR spare3[8];
// System Battery
BOOLEAN SystemBatteriesPresent;
BOOLEAN BatteriesAreShortTerm;
BATTERY_REPORTING_SCALE BatteryScale[3];
// Wake
SYSTEM_POWER_STATE AcOnLineWake;
SYSTEM_POWER_STATE SoftLidWake;
SYSTEM_POWER_STATE RtcWake;
SYSTEM_POWER_STATE MinDeviceWakeState; // note this may change on driver load
SYSTEM_POWER_STATE DefaultLowLatencyWake;
} SYSTEM_POWER_CAPABILITIES, *PSYSTEM_POWER_CAPABILITIES;
typedef struct {
BOOLEAN AcOnLine;
BOOLEAN BatteryPresent;
BOOLEAN Charging;
BOOLEAN Discharging;
BOOLEAN Spare1[4];
ULONG MaxCapacity;
ULONG RemainingCapacity;
ULONG Rate;
ULONG EstimatedTime;
ULONG DefaultAlert1;
ULONG DefaultAlert2;
} SYSTEM_BATTERY_STATE, *PSYSTEM_BATTERY_STATE;
// end_winnt
// end_nthal
typedef struct _PROCESSOR_POWER_INFORMATION {
ULONG Number;
ULONG MaxMhz;
ULONG CurrentMhz;
ULONG MhzLimit;
ULONG MaxIdleState;
ULONG CurrentIdleState;
} PROCESSOR_POWER_INFORMATION, *PPROCESSOR_POWER_INFORMATION;
typedef struct _SYSTEM_POWER_INFORMATION {
ULONG MaxIdlenessAllowed;
ULONG Idleness;
ULONG TimeRemaining;
UCHAR CoolingMode;
} SYSTEM_POWER_INFORMATION, *PSYSTEM_POWER_INFORMATION;
#ifdef __cplusplus
}
#endif
#endif // _NTPOAPI_