idlestat - A CPU power-state analysis tool.
Trace mode:
- idlestat --trace -f|--trace-file filename -t|--duration
seconds [OPTION] [command]
Reporting mode:
- idlestat --import -f|--trace-file filename
[OPTION]
Idlestat comes with two modes: in trace mode, it
measures how long the CPUs have been in the different idle and operating
states, analyzes captured events, logs them, and generates a report; in
reporting mode, it reads the trace file, analyzes logged events in
the trace file, and generates a report. A report by idlestat shows
statistics of power related states. Currently, it handles P-states,
C-states, and IRQ states.
For trace mode, idlestat relies on the kernel's FTRACE
function to monitor and capture C-state and P-state transitions of CPUs over
a time interval. That is, for trace mode, idlestat needs a kernel with
FTRACE related configurations enabled. And since it uses FTRACE, root
privilege is needed when running in trace mode. Idlestat extracts the
following information from trace file:
-
- Times when CPUs entered and exited a certain C-state
-
- Times when CPUs entered and exited a certain P-state
-
- Raised IRQs
Following a successful run, idlestat calculates and reports the
following information:
- -
- Total, average, minimum, and maximum time spent in each C-state,
per-CPU.
- -
- Total, average, minimum, and maximum time spent in each P-state,
per-CPU.
- -
- Total, average, minimum, and maximum time during which all CPUs in a
cluster were in a "shallowest" (closest to running) state of all
the constituent CPUs.
- -
- Number of times a certain IRQ caused a CPU to exit idle state, per-CPU and
per-IRQ
- --trace
- Run idlestat in trace mode, as noted above, root privilege is needed. Used
with -t and -f to specify running duration and trace output
filename, respectively.
- --import
- Run idlestat in reporting mode. Used with -f to specify the trace
file to import.
- -f, --trace-file
filename
- Specify the trace filename to generate (for --trace) or read (for
--import).
- -t, --duration
seconds
- Time to capture in seconds
- [command]
- If the command argument is given, idlestat will fork a child to run the
command so that you can capture related states when the command is
running. Note that if the running command does not terminate before the
time specified by -t, idlestat will send a SIGTERM to the child
process to ask it to terminate. If the command to run lasts less than the
time specified by -t, idlestat will terminate after the command
finished.
When there is no command, idlestat does trace capture and
other works dutifully.
- -b, --baseline_trace
baseline_filename
- Specify baseline filename for trace comparison. See COMPARISON and
EXAMPLES for more information.
- -c, --idle
- Show idle, C-state in ACPI term, statistics. This is the default mode if
neither -w nor -p is set. Note that -w, -c,
and -p are not exclusive, that is, you can choose any combination
of the three.
- -e,
--energy-model-file energy_model
- Specify energy model file. See ENERGY MODEL for the description of
the energy file format.
- -h, --help,
-?
- Print simple help messages.
- -o, --output-file
filename
- Specify the file name to output statistics. If not specified, statistics
are printed to stdout.
- -p,
--frequency
- Show cpufreq (or say P-state) statistics.
- -r,
--report-format
- Specify the report format. Valid types are: default, boxless, csv, and
comparison.
- -v, --verbose
- Specify the verbosity level. This option could be specified multiple
times. Each copy of the option increases verbosity level by one, currently
the highest verbosity level used for any message is 2.
- -w, --wakeup
- Show wakeup statistics.
- -B, --boxless
- Set the report format to boxless
- -C, --csv
- Set the report format to comma separated values (CSV)
- -I,
--poll-interval
- Set kernel polling interval, which is used to determine if it’s
time move data from kernel FTRACE buffer to other places.
- -S,
--buffer-size
- Set the kernel FTRACE buffer size to use.
- -V, --version
- Show idlestat version information and exit.
The comparison report is used to compare changes between the
active trace (specified by -f,--trace-file) and the baseline
trace. It becomes active by providing a baseline trace
(-b,--baseline_trace) and specifying the comparison report
style with "-r comparison".
The following describes the format of idlestat energy model files
(using the included energy_model file as an example):
Lines starting with # or which are blank are ignored.
First, specify how many clusters there are.
clusters 1
For each cluster (named clusterA, clusterB, etc.) specify how many
cap states and C states there are. Idlestat will check that the correct
number of clusters are provided.
#
clusterA: 16 cap states 5 C states
Then specify the name, cluster power and core power for each
P-state (idlestat will check if there are the correct number of P-states
provided) in the cluster.
P-states:
# speed, cluster power, core power
2901 6200 3200
2900 6190 3190
2800 6180 3180
2700 6170 3170
2500 6160 3160
2400 6150 3150
2300 6140 3140
2200 6130 3130
2000 6120 3120
1900 6110 3110
1800 6100 3100
1700 6090 3090
1600 6080 3080
1400 6070 3070
1300 6060 3060
1200 6050 3050
Then specify the name, cluster power and core power for each C-state (idlestat
will check if there are the correct number of C-states provided) in the
cluster.
C-states:
C1-IVB 25 0
C1E-IVB 30 0
C3-IVB 35 0
C6-IVB 40 0
C7-IVB 35 0
Finally, specify the wakeup power.
wakeup 210 6
Repeat for each cluster.
Idlestat has its own trace file format, which is based on ftrace's
format (see Documentation/trace/ftrace.txt in kernel source). Besides
standard FTRACE entries, idlestat adds CPU topology, C-state information,
and some artificial P-State entries. Idlestat can also import standard
FTRACE format and "trace-cmd report" format. Note that since there
is no CPU topology and C-state information in FTRACE or trace-cmd trace
files, they should be used on the machines those traces are captured.
Currently, idlestat supports four report formats: default,
boxless, csv, and comparison.
- 1.
- default: show C-state, P-State, and IRQ state statistics tables if
corresponding -c, -p, and -w command line options are set. Tables come
with - and | as boundaries.
- 2.
- boxless: it's the default without - and | as table boundaries. This is
more Braille terminal friendly than the default one
- 3.
- csv: comma separated values. This is easier to process with scripting
languages, such as awk and perl. Also it's easier to be processed with
spreadsheet software.
- 4.
- comparison: This is similar to default report style, except that it
displays changes in active trace compared to the baseline trace. It
becomes active by providing a baseline trace (--baseline) and specifying
the comparison report style with "-r comparison".
Assuming the idlestat binary is in your PATH.
- 1.
- Run a trace, post-process the results (default is to show only C-state
statistics):
sudo idlestat --trace -f /tmp/mytrace -t 10
- 2.
- Run a trace, post-process the results and print all statistics:
sudo idlestat --trace -f /tmp/mytrace -t 10 -p -c
-w
- 3.
- Run a trace with an external workload, post-process the results:
sudo idlestat --trace -f /tmp/mytrace -t 10 -p -c -w --
rt-app /tmp/mp3.json
- 4.
- Post-process a trace captured earlier:
idlestat --import -f /tmp/mytrace
- 5.
- Run a trace, post-process the results and print all statistics into a
file:
sudo idlestat --trace -f /tmp/mytrace -t 10 -p -c -w -o
/tmp/myreport
- 6.
- Run a comparison trace, say, before and after making changes to system
behavior
sudo idlestat --trace -f /tmp/baseline -t 10
sudo idlestat --trace -f /tmp/changedstate -t 10
idlestat --import -f /tmp/changedstate -b /tmp/baseline -r comparison
During the acquisition, idlestat tries to stay quiescent to
prevent disturbing the traces. For this reason the traces are buffered in a
fixed buffer size. If the duration of the acquisition produces more traces
than what the buffer is capable to store, that will result in a truncated
result.
Started by
Daniel Lezcano
with contributions from others. See the git log of the source code
(https://git.linaro.org/power/idlestat.git) for all the contributors.
Copyright © 2015, Linaro Limited. License GPLv2: GNU GPL
version 2
http://gnu.org/licenses/gpl.html.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Or, say, there is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.