Power Management Test Tool (PwrTest)

Article
01/05/2010

Overview

PwrTest is a test tool that enables developers, testers and system integrators to exercise and record power management information from the system. PwrTest can be used to automate sleep and resume transitions as well as record processor power management and battery information from the system over a period of time.

PwrTest features robust logging and a command-line interface. PwrTest is capable of logging information to both a Windows Test Technologies (WTL) and XML file format.

Details

PwrTest functionality is separated into scenarios. Currently, PwrTest supports the following scenarios:

Run Time:
Log File:
System Restart Required: Test Category:
Supported operating systems for Logo or Signature testing:

Windows 7
Windows Server 2008 R2
SLEEP
Exercises sleep and resume transition functionality. Sleep/resume transitions can be automated and target sleep states can be specified.
PPM
Displays and records processor power management (PPM) information and metrics. Performance (ACPI P states) and processor idle (ACPI C states) state information can be logged for a period of time at a specified interval.
BATTERY
Displays and records battery information and metrics. Battery capacity, voltage, rate of drain and estimated life time remaining can be logged for a period of time at a specified interval.
INFO
Displays system power management information, such as available sleep states and processor power management capabilities.
ES
Displays and records thread execution state changes. Thread execution states allow applications and services to temporarily override power management settings such as the monitor and sleep idle timeouts.

Command-Line Arguments

PwrTest functionality and scenarios can be accessed through the command-line. The basic usage for PwrTest is:

usage: PwrTest /scenario [-l:path]

scenario indicates the test scenario

  sleep    for sleep/resume transition testing
  ppm       for processor power management testing
  battery   for battery information testing
  info      for system capabilities information
  es        for thread execution state changes

path indicates the logfile path

For example, c:\logfile.xml
Default is .\PwrTest.xml

The logfile path can be specified as the name of the target file in the current directory, or as the path and target file in another directory. PwrTest will automatically generate an XML and WTL version of the log with the same file name and “.XML” or “.WTL” appended at the end of the file name.

To learn more about each of the PwrTest scenarios, type:

PwrTest /<scenario> /?

Log File Information

PwrTest supports both XML and WTL log file formats. By default, PwrTest will generate both the XML and WTL logs named “PwrTestlog.xml” and “PwrTestlog.wtl”, respectively. These files will be generated in the current directory.

You can use the –l:path argument to specify a different path and file name for the PwrTest log files. For example, -l:\\server\share\PwrTest_today\run will generate the files run.xml and run.wtl in the folder \\server\share\PwrTest_today\.

The WTL log file format is common to all Microsoft Windows Driver Kit (WDK) tools that use the WTTlog interface.

The PwrTest XML log file format is described in detail with the scenario information below. However, all PwrTest XML log files have the following root element:

      <PwrTestLog
            date=”today’s date”
            time=”beginning time”
            filename = “logfile path”>
      … scenario information …
      </PwrTestLog>

Sleep Scenario Information

The PwrTest Sleep scenario is designed to facilitate automated testing of sleep and resume transitions. PwrTest is capable of directing the platform into one or more sleep states in an automated fashion and logging sleep state performance information such as the BIOS initialization and total resume times.

To learn more about the Sleep Scenario, type:

PwrTest /sleep /?

The PwrTest Sleep scenario supports the command-line arguments in the following table.

Argument	Description	Default value
/c:n	n indicates the number of sleep cycles	/c:1
/d:n	n indicates the delay time between consecutive sleep cycles, in seconds.	/d:90
/p:n	n indicates the time the system will sleep before automatically waking for the next sleep cycle, in seconds.	/p:60
/h:y	Indicates hybrid sleep transitions should be enabled.	Current user power policy
/h:n	Indicates hybrid sleep transitions should be disabled.	Current user power policy
/t:y	Indicates sleep transitions should be marked critical. Applications and services are not able to prevent the sleep transition.	Current user power policy
/t:n	Indicates sleep transitions should not be marked critical. Applications and services are able to prevent the sleep transition.	Current user power policy
/s:n	n indicates the target sleep state(s) for the sleep transitions. Possible values are: “all”, All ACPI sleep states should be used in sequential order (S1, S3, S4, S1, S3, S4…) “rnd”, All ACPI sleep states should be used in random order (S1, S4, S3, S1, S4, S1…) “1”, Only S1 state should be used. “3”, Only S3 state (“Standby”) should be used. “4”, Only S4 state (“Hibernate”) should be used.	/s:3
/unattend	Indicates the system should wake unattended. PwrTest will not request the display to be enabled between each sleep cycle.	This feature is disabled by default.

Examples

PwrTest /sleep /c:7 /s:3

PwrTest will cycle the system through 7 standby transitions and save the output file information to .\PwrTestlog.xml and .\PwrTestlog.wtl.

PwrTest /sleep /c:1 /s:1

PwrTest will cycle the system through a single S1 transition and save the output file information to .\PwrTestlog.xml and .\PwrTestlog.wtl.

PwrTest /sleep /c:10 /s:rnd /d:180 /p:600 /l:random

PwrTest will cycle the system through 10 sleep/resume cycles with a random target sleep state from the available sleep states on the system. The system will sleep for 10 minutes on each sleep cycle and the delay between sleep cycles will be 3 minutes. The output will be saved to .\random.xml and .\random.wtl.

XML Logfile Output

The Sleep scenario generates the following XML elements:

This table describes the Sleep scenario XML elements in detail.

Element	Description
<SleepScenario>	Contains information related to the sleep scenario. Only one <SleepScenario> element per PwrTest log file.
<SleepTransitions>	Provides overall data about the sleep transition cycles such as the state of critical and hybrid sleep features.
<SleepTransition>	Provides per-sleep cycle information such as the start and end times, as well as details about the resume time such as the BIOS initialization time. A <SleepTransition> element is generated for each sleep transition cycle.
<StartT>	Indicates the start time of the sleep cycle. (hh:mm:ss)
<EndT>	Indicates the end time of the sleep cycle. (hh:mm:ss)
<Duration>	Indicates the duration of the sleep cycle. (hh:mm:ss)
<TargetState>	Indicates the target sleep state.
<EffectiveState>	Indicates the effective sleep state.
<BIOSInit>	Indicates the amount of time required to initialize the BIOS (TargetState must be 3) on resume in milliseconds.
<DriverInit>	Indicates the amount of time required to initialize drivers on resume in milliseconds.
<Suspend>	Indicates the amount of time required to suspend the system in milliseconds.
<Resume>	Indicates the total amount of time required to resume the system in milliseconds.
<HiberRead>	Indicates the time required to read the hibernation file in milliseconds. (TargetState must be 4)
<HiberWrite>	Indicates the time required to write the hibernation file in milliseconds. (EffectiveState must be 4)

PPM Scenario Information

The PwrTest PPM scenario is designed to facilitate automated inspection of processor power management capabilities and run-time information. PwrTest is capable of recording system usage of processor performance and processor idle states over a duration of time.

These metrics can be analyzed post-run from the PwrTest logfile and compared to past or future runs of PwrTest.

To learn more about the PPM Scenario, type:

PwrTest /ppm /?

The PwrTest PPM scenario supports the command-line arguments in the following table.

Argument	Description	Default value
/n:n	n indicates the number of cycles of processor information to log.	/c:100
/i:n	n indicates the polling interval (in milliseconds) to update processor information. PwrTest will record processor information for the number of cycles specified by /n:n multiplied by the polling interval specified by /i:n.	/i:5000
/c:y	Indicates that processor idle (ACPI C-state) information should be logged.	(default)
/c:n	Indicates that processor idle (ACPI C-state) information should not be logged.
/p:y	Indicates that processor performance / throttle state information should be logged.	(default)
/p:n	Indicates that processor performance / throttle state information should not be logged.
/u:y	Indicates that CPU utilization information should be logged.	(default)
/u:n	Indicates that CPU utilization information should not be logged.

Examples

PwrTest /ppm /n:10 /i:6000

PwrTest will record all processor power management information for one minute at 6 second intervals.

PwrTest /ppm /n:3600 /i:1000 /p:n

PwrTest will record processor performance state information every second for an hour.

PwrTest /ppm /n:3600 /i:1000 /u:y /p:n /c:n

PwrTest will record processor utilization only for one-second intervals for an hour.

XML Logfile Output

The PPM scenario generates the following XML elements:

This table describes the PPM scenario XML elements in detail.

Element	Description
<PPMScenario>	Contains information related to the PPM scenario. Only one <SleepScenario> element per PwrTest log file.
<ProcessorInformation>	Contains information related to the static attributes of the processor, such as performance and throttle state capabilities.
<PerformanceStates>	Contains a list of <PerformanceState> elements.
<PerformanceState>	Indicates an available performance or throttle state. Includes state number, frequency, percentage of maximum frequency and type attributes.
<ProcessorName>	Indicates the friendly name of the processor.
<InterfaceType>	Indicates the mechanism used to interface between Windows and platform processor power management features.
<TransitionLatency>	Indicates the latency when switching performance states. Includes an units attribute, typically “us”.
<ProcessorTraces>	Contains a list of <Trace> elements. Includes an interval attribute indicating the interval of each <Trace> element.
<Trace>	Contains trace information, which will vary depending on the command-line arguments presented to PwrTest.
<CpuId>	Identifies the processor.
<ElapsedT>	Indicates the elapsed time since the start of PwrTest in milliseconds.
<CPUIdle>	Indicates the percentage of processor idle time.
<PState>	Indicates the current processor performance state.
<Frequency>	Indicates the actual frequency of the current processor performance state in Megahertz.
<PercentOfMax>	Indicates the percentage of maximum frequency for the current performance state.
<PStateType>	Indicates if the performance state is a performance state (1) or a throttle state (0).
<COne>	Indicates the percentage of CPU idle time spent in the C1 CPU idle state.
<CTwo>	Indicates the percentage of CPU idle time spent in the C2 CPU idle state.
<CThree>	Indicates the percentage of CPU idle time spent in the C3 CPU idle state.

Battery Scenario Information

The PwrTest Battery scenario is designed to facilitate automated inspection of battery and power source information. PwrTest is capable of logging battery capacity, voltage, rate of drain and general state for up to two batteries on the system. Battery data is logged at a specified interval for a specified number of cycles.

To learn more about the Battery Scenario, type:

PwrTest /battery /?

The PwrTest Battery scenario supports the command-line arguments in the following table.

Argument	Description	Default value
/n:n	n indicates the number of cycles of battery information to log.	/c:100
/i:n	n indicates the polling interval (in milliseconds) to update battery information.	/i:5000
/b:n	n indicates the which battery to log information from (0 or 1).	/b:all
/b:all	Indicates battery information should be logged from all batteries.	/b:all

Examples

PwrTest /battery /n:10 /i:6000

PwrTest will record all battery information for one minute at 6 second intervals.

PwrTest /battery /n:10 /i:6000 /b:0

PwrTest will record battery information only from battery 0 for one minute at 6 second intervals.

XML Logfile Output

The Battery scenario generates the following XML elements:

This table describes the Battery scenario XML elements in detail.

Element	Description
<BatteryScenario>	Contains information related to the battery scenario. Only one <BatteryScenario> element per PwrTest log file.
<Batteries>	Contains information related to the static attributes of the system batteries, such as manufacturer and cycle count information. Note, all information may not be available for each battery.
<Battery>	Contains static information about a system battery. An id attribute is present to uniquely identify the battery.
<Name>	Indicates the name of the battery.
<UniqueID>	Indicates the unique ID of the battery.
<Chemistry>	Indicates battery chemistry.
<Manufacturer>	Indicates the battery manufacturer.
<DesignedCapacity>	Indicates the designed capacity of the battery in mWh.
<FullChargeCapacity>	Indicates the fully charged capacity of the battery in mWh.
<CriticalBias>	Indicates a bias from zero, in mWh, which is applied to the battery reporting.
<CycleCount>	Indicates the number of charge/discharge cycles the battery has experienced.
<ManufactureDate>	Indicates the manufacture date of the battery.
<FullLifeTime>	Indicates the battery full life time in seconds.
<BatteryTraces>	Contains a list of <Trace> elements. Has an attribute indicating the battery information polling interval.
<Trace>	Contains information about battery status such as voltage, capacity and rate of drain for a given interval.
<ElapsedT>	Indicates the elapsed time since PwrTest was started.
<ACStatus>	Indicates if the system is running on AC (1) or battery (0) power.
<TimeRemaining>	Indicates the battery life time remaining from all system batteries, in seconds.
<Capacity>	Indicates the capacity of the battery in mWh. Has an id attribute to indicate which battery the capacity is being reported for.
<RateOfDrain>	Indicates the rate of drain of the battery in mW. Has an id attribute to indicate which battery the rate of drain is being reported for.
<Voltage>	Indicates the battery voltage in mV. Has an id attribute to indicate which battery the voltage is being reported for.

Info Scenario Information

The PwrTest Info scenario is designed to log and display system power management capabilities and information, such as the availability of system power states.

To learn more about the Info Scenario, type:

PwrTest /info /?

The PwrTest Info scenario supports the command-line arguments in the following table.

Argument	Description	Default value
/info:powercap	Display SYSTEM_POWER_CAPABILITIES, which includes information about the availability of system sleep states.	(none)
/info:powerinfo	Display SYSTEM_POWER_INFORMATION which displays dynamic data about current idle thresholds and timers.	(none)
/info:battery	Display SYSTEM_BATTERY_STATE which contains information about the current state of the system battery.	(none)
/info:ppm	Display PROCESSOR_POWER_INFORMATION which contains information about the system processor.	(none)
/info:all	Display all supported information data.	(none)

Examples

PwrTest /info:powercap

PwrTest will display and log system power capabilities information from the SYSTEM_POWER_CAPABILITIES structure.

PwrTest /info:all

PwrTest will display and log all supported information data.

XML Logfile Output

The Info scenario generates the following XML elements:

The following table describes the Info scenario XML elements in detail.

Element	Description
<InfoScenario>	Contains information related to the info scenario. Only one <InfoScenario> element per PwrTest log file.
<SYSTEM_POWER_CAPABILITIES>	Contains information related to system power capabilities. This information is retrieved from the SYSTEM_POWER_CAPABILITIES structure.
<SystemSxStateSupported>	Indicates if a given system ACPI sleep state is supported on the system.
<RtcWakeSupported>	Indicates the lowest sleep state where RTC wake (wake on timer) is supported. The value is of the SYSTEM_POWER_STATE enumeration.
<FastSystemS4>	Indicates if hybrid sleep is available on the system.
<SYSTEM_POWER_INFORMATION>	Contains information related to the idleness of the system.
<MaxIdlenessAllowed>	Indicates the idleness (in percentage) when the system is considered idle and the idle timeout begins counting.
<Idleness>	Current idle level, expressed in percentage.
<TimeRemaining>	Indicates the time remaining in the system standby idle timer, in seconds.
<CoolingMode>	Indicates the current system cooling mode: (0) Active, (1), Passive, (2) Invalid.
<SYSTEM_BATTERY_STATE>	Contains information related to the current state of the system battery.
<AcOnLine>	Indicates if the system is currently operating on AC power.
<BatteryPresent>	Indicates if at least one battery is present in the system.
<Charging>	Indicates if at least one battery is currently charging.
<Discharging>	Indicates if at least one battery is currently discharging.
<MaxCapacity>	Maximum capacity of the battery when new, in mWh.
<RemainingCapacity>	Estimated remaining capacity of the battery, in mWh.
<RateOfDrain>	Indicates the current rate of discharge of the battery in mW.
<EstimatedTime>	Estimated time remaining on the battery, in seconds.
<DefaultAlert1>	Indicates the battery manufacturers suggested capacity when a low battery alert should occur.
<DefaultAlert2>	Indicates the battery manufacturers suggested capacity when a warning battery alert should occur.
<PROCESSOR_POWER_INFORMATION>	Contains information related to the system processors and their power management capabilities.
<CPUNumber>	Indicates which processor the current <PROCESSOR_POWER_INFORMATION> element is describing.
<MaxMhz>	Indicates the maximum frequency of the processor.
<CurrentMhz>	Indicates the current frequency of the processor.
<MhzLimit>	Indicates the current limit on the processor clock frequency.
<MaxIdleState>	Indicates the maximum idle state of the processor.
<CurrentIdleState>	Indicates the current idle state of the processor.

Execution State Scenario Information

The PwrTest Execution State scenario is designed to log and display thread execution state change events.

Applications and services may temporarily override power management settings such as the monitor and sleep idle time outs by changing their thread execution state. Execution state for a given thread can be changed through the Microsoft Win32 SetThreadExecutionState() API.

The Execution State scenario will display and log in real-time applications and services that are changing their thread execution state. This can be useful to diagnose applications and services that are preventing the monitor or system from going idle.

For more information about the SetThreadExecutionState() API, see SetThreadExecutionState on the MSDN Web site.

To learn more about the Execution State scenario, type:

PwrTest /es /?

The PwrTest /es scenario can be exited by pressing the ‘q’ key.

Note PwrTest is not capable of determining changes to thread execution state before the Execution State scenario is started.

Argument	Description	Default value
(no arguments)	n/a	n/a

Examples

PwrTest /es

PwrTest will display and log changes to thread execution state.

XML Logfile Output

The Execution State scenario generates the following XML elements:

<ExecutionState>
    <EsChange>
      <Time>09:13:47</Time>
      <Process>\Device\HarddiskVolume1\Program Files\Windows Media Player\wmplayer.exe</Process>
        <RawState>0x80000001</RawState>
        <Continuous>TRUE</Continuous>
        <System>TRUE</System>
        <Display>FALSE</Display>
        <AwayMode>FALSE</AwayMode>
    </EsChange>
    <EsChange>
      <Time>09:13:47</Time>
      <Process>\Device\HarddiskVolume1\Program Files\Windows Media Player\wmplayer.exe</Process>
        <RawState>0x80000003</RawState>
        <Continuous>TRUE</Continuous>
        <System>TRUE</System>
        <Display>TRUE</Display>
        <AwayMode>FALSE</AwayMode>
    </EsChange>
  </ExecutionState>

The following table describes the Execution State scenario XML elements in detail.

Element	Description
<ExecutionState>	Contains information related to the execution state scenario. Only one <ExecutionState> element per PwrTest log file.
<EsChange>	Contains information related a single thread execution state change event. There will be one <EsChange> element for each thread execution state change event recorded in the PwrTest log file.
<Time>	Indicates the time when the execution state change event occurred.
<Process>	Indicates the path to the image file for the process that requested the execution state change.
<RawState>	Indicates the request execution state. This state is a 32-bit value of type EXECUTION_STATE (see Windows.h).
<Continuous>	Indicates if the process requested the execution state change to be continuous (ES_CONTINUOUS).
<System>	Indicates if the process requested the system to be available (ES_SYSTEM_REQUIRED).
<Display>	Indicates if the process requested the display to be available (ES_DISPLAY_REQUIRED).
<AwayMode>	Indicates if the process requested away mode to be enabled (ES_AWAYMODE_REQUIRED).

Run Time: 10 minutes
Log File: PwrTestLog.xml
System Restart Required: No
Test Category:
Supported operating systems for Logo or Signature testing:

Windows Vista

Program:

Requirements

Software Requirements

The test tool requires the following software:

Supported operating system (see list above)
Software components included with the device that is being tested

Hardware Requirements

The test tool requires the following hardware:

Device to be tested
Computer that meets the minimum software requirements
Windows keyboard
Two-button pointing device
Color display monitor capable of at least 1024 by 768 resolution, 32-bits per pixel, 60 Hz
Software components included with the device that is being tested.
Hard drive with a minimum of 20 GB available on partition C:

Processor

The test tool runs on the following processor architectures:

x86
x64
Itanium

Running Power Management Test Tool (PwrTest)

Code Tour

File Manifest

File	Location
pwrtest.exe	tools\acpi\pwrtest

Test Assertions

S3 Resume

Test Assertion GUID: C98100E4-BF10-431e-B803-BD1292276285

Windows Logo Program: SYSFUND-0004 System resumes from ACPI S3 state in ≤2 s

Additional Information:

Send feedback on this topic
Built on December 10, 2009

Power Management Test Tool (PwrTest)

Overview

Details

Requirements

Running Power Management Test Tool (PwrTest)

Code Tour

Test Assertions

Additional resources