Provided by: idlestat_0.8-8_amd64 bug

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.

SEE ALSO

       trace-cmd(1), trace-cmd-format(1), trace-cmd.dat(5)