Ubuntu Manpage: idlestat - A CPU power-state analysis tool.

name
synopsis
description
options
comparison
energy model
trace file format
report formats
examples
limitations
author
reporting bugs
copyright
see also

NAME

       idlestat - A CPU power-state analysis tool.

SYNOPSIS

       Trace mode:

              idlestat --trace -f|--trace-file filename -t|--duration seconds [OPTION] [command]

       Reporting mode:

              idlestat --import -f|--trace-file filename [OPTION]

DESCRIPTION

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

OPTIONS

--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.

COMPARISON

       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".

ENERGY MODEL

       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.

TRACE FILE FORMAT

       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.

REPORT FORMATS

       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".

EXAMPLES

       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

LIMITATIONS

       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.

AUTHOR

       Started by Daniel Lezcano ⟨daniel.lezcano@linaro.org⟩ with contributions from others.  See the git log of
       the source code (https://git.linaro.org/power/idlestat.git) for all the contributors.

REPORTING BUGS

       Send  mail to ⟨sched-tools@linaro.org⟩.  Or, submit bugs at ⟨https://bugs.linaro.org/enter_bug.cgi⟩ under
       Product "power management", Component "idlestat".

COPYRIGHT

       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.