Energy Analysis User Guide

User Guide

  • 2020
  • 05/25/2022
  • Public Content
Contents

Intel® SoC Watch Command-line Tool Options

Options and example commands for running Intel® SoC Watch energy analysis collection.
The Intel SoC Watch command-line tool has the following general syntax:
socwatch <general options> <collection options> <reporting options>
A complete list of options is found in the Intel SoC Watch User's Guide. A list of options supported on the current platform is available using the
--help
 option.
After collection starts, any feature specified on the command line that is not supported by the current platform is reported in the command window, but collection continues if there is at least one valid feature to collect. Collection terminates for one of three reasons:
  • The specified run time has elapsed. This occurs only if the
    --time
     option was included in the command.
  • The program has exited. This occurs only if the
    --program
     option was included in the command.
  • Ctrl+C was entered.
The location and name of the result files is displayed in the command window at the end of collection. A summary file (
*.csv
) is available after collection completes. See the
Intel SoC Watch User's Guide
 (Linux* or Android* | Windows*) for more information about features, options, and output files.

Basic Command Options

The following table lists basic command options and a brief description of the option's use. Additional options and more information is available from the
Intel SoC Watch User's Guide
 (Linux or Android | Windows).
Option
Possible Values
Description
-h
--help
Display text describing tool options and usage.
-f
--feature
cpu
: CPU C-state and P-State residencies
gfx
: Graphics C-state and P-state residencies
device
: Device low power state residencies
temp
: Core and SoC temperatures
sys
: Many system metrics, including the above groups and more.
Specify the features to collect. This option can be use dmultiple times in the same command to collect many features at the same time. See the
Intel SoC Watch User's Guide
 for your operating system to learn about feature names for all platforms. Use the
--help
 option to discover features supported for the current platform.
-m
--max-detail
Collect all data available for each specified feature.
-o
--output
<filename>
Specify a name under which the collection of data files is grouped. If this option is not specified, the default name is
SOCWatchOutput
.
-p
--program
<exename> [<args>]
Specify the name of an executable to be started automatically prior to collection. The name can be followed by zero or more arguments that are passed to the program. This option must be specified at the end of the command because everything following the executable name is treated as an argument.
-s
--start-delay
<seconds>
Specify a number of seconds to wait before starting data collection.
-t
--time
<seconds>
Specify the collection duration in seconds.
-r
--result
sum
: Generate a summary report of all collected metrics (
*.csv
).
int
: Generate a trace (timeline) report of all collected metrics (
trace.csv
). Use the
-m
 option with this option.
vtune
: Generate a file that can be to be imported into
Intel® VTune™
Profiler
 (
*.pwr
) .
json
: Generate a detail report that can be viewed in Intel System Studio (
*.swjson
).
Specify the type of result to be generated. This option can be used multiple times in the same command to produce multiple types of reports.
-i
--input
<filename>
Specify the filename without the file extension of an existing collection. This option is used to generate additional reports for an existing collection.
Detailed reports collected over a long period of time can take several minutes to generate. Do not specify
int
/
vtune
/
json
 result formats with the collection command. If you decide you need that detail after viewing the summary result, use the
--input
 option to generate additional report formats.
Example Commands
Use the following command to collect and report CPU C-state and P-state residency data and system sleep state residency for the platform for 30 seconds. Intel SoC Watch will write a summary report to the file
SoCWatchOutput.csv
. 
socwatch -t 30 -f cpu -f sstate
Use the following command to collect and report on a comprehensive set of metrics for the platform and to name the output files
run1
 rather than the default
SoCWatchOutput
. You can include a folder name in the string to group the files under a folder. If the folder does not already exist, it will be created. 
socwatch -t 30 -f sys -o run1
Use the following command to collect and report on a comprehensive set of platform energy metrics with maximum detail and produce a trace report in addition to the summary report. All results are in files named
run1
 under the folder
sysDetail
. The summary reports are in
run1.csv
 and the trace report are in
run1_trace.txt
. 
socwatch -t 60 -f sys -m -r int -o sysDetail/run1
Use the following command to collect and report on a comprehensive set of platform energy metrics with maximum detail and generate an export file that can be opened in
Intel VTune
Profiler
. 
socwatch -t 30 -f sys -r vtune -m -o run1

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.