Intel® SoC Watch Command-line Tool Options

Options and example commands for running Intel® SoC Watch energy analysis collection.

Note

Energy analysis with the Intel® SoC Watch data collector is available for target Android*, Windows*, or Linux* devices and provided only with the Intel® VTune™ Amplifier for Systems.

The Intel® SoC Watch command-line tool is used with the following syntax:

socwatch <general options> <collection options> <reporting options>

When the program starts, the command lists the types of data it will collect based on what is found in the command options. If a collection option is not supported, Intel SoC Watch displays a warning for each unsupported feature. Collection will proceed if at least one feature is valid. Intel SoC Watch terminates collection for one of three reasons:

The specified run time has elapsed. This option is only valid if the --time option was included in the command.
The program has exited. This option is only valid if the --program option was included in the command.
Ctrl+C was entered.

The location and name of the output is displayed in the command prompt at the end of collection. A summary file (*.csv) is available after collection completes. If detailed collection and reports were requested, the additional reports and output files (.txt) are available. See the Intel SoC Watch User's Guide (socwatch_<OS>_users_guide.pdf) for more information about the reports 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 (socwatch_<OS>_users_guide.pdf).

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 `energy`: (Windows* OS only) Battery, package, core, and graphics energy consumption `sys`: Most system metrics, including C/P/S/D states, temperature, total memory bandwidth, and so on. Additional feature options are listed in the Intel SoC Watch User's Guide.	Specify which group of features to collect. See the Intel SoC Watch User's Guide for your platform to learn about all of the individual feature names.
`-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`: Summary reports of OS and hardware metrics `detail`: (Windows* only) Summary and detail reports for OS and hardware metrics. This option can only be used with the `--max-detail` option. `sww`: (Windows only) Generate a summary and export file (.sww1) to be imported into Intel VTune™ Amplifier for Systems `int`: (Linux/Android only) Summary and detail reports for OS and hardware metrics. This option can only be used with the `--max-detail` option. `vtune`: (Linux/Android only) Generate a summary and export file (.pwr) to be imported into Intel VTune™ Amplifier for Systems `raw`: (Linux/Android only) Generate a detailed text file summary report for metrics. Additional result options are listed in the Intel SoC Watch User's Guide.	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 reports for an existing collection. Tip Detailed reports collected over a long period of time can take many minutes to generate. Use the `--input` option after the initial collection to generate detailed reports for lengthy collections if the summary report indicates a need for more detail.

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 detailed reports in addition to the summary reports. All results are in files named run1 under the folder sysDetail. The summary reports are in run1.csv and the detailed reports are in run1.txt. For Windows, various timeline CSV reports are generated with _timeline or _t1 in the name.

For Windows:

socwatch -t 60 -f sys -m -r detail -o sysDetail/run1

For Linux/Android:

./socwatch -t 60 -f sys -r int -r raw -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 containing all supported metrics that can be opened in Intel VTune Amplifier for Systems.