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--timeoption was included in the command.
- The program has exited. This occurs only if the--programoption 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