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.
TIP:
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 sstateUse 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 run1Use 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/run1Use 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 Parent topic: Energy Analysis User Guide