Documentation/cpu-freq/cpufreq-stats.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==========================================
   4 General Description of sysfs CPUFreq Stats
   5 ==========================================
   6
   7 information for users
   8
   9
  10 Author: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
  11
  12 .. Contents
  13
  14    1. Introduction
  15    2. Statistics Provided (with example)
  16    3. Configuring cpufreq-stats
  17
  18
  19 1. Introduction
  20 ===============
  21
  22 cpufreq-stats is a driver that provides CPU frequency statistics for each CPU.
  23 These statistics are provided in /sysfs as a bunch of read_only interfaces. This
  24 interface (when configured) will appear in a separate directory under cpufreq
  25 in /sysfs (<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/) for each CPU.
  26 Various statistics will form read_only files under this directory.
  27
  28 This driver is designed to be independent of any particular cpufreq_driver
  29 that may be running on your CPU. So, it will work with any cpufreq_driver.
  30
  31
  32 2. Statistics Provided (with example)
  33 =====================================
  34
  35 cpufreq stats provides following statistics (explained in detail below).
  36
  37 -  time_in_state
  38 -  total_trans
  39 -  trans_table
  40
  41 All the statistics will be from the time the stats driver has been inserted
  42 (or the time the stats were reset) to the time when a read of a particular
  43 statistic is done. Obviously, stats driver will not have any information
  44 about the frequency transitions before the stats driver insertion.
  45
  46 ::
  47
  48     <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l
  49     total 0
  50     drwxr-xr-x  2 root root    0 May 14 16:06 .
  51     drwxr-xr-x  3 root root    0 May 14 15:58 ..
  52     --w-------  1 root root 4096 May 14 16:06 reset
  53     -r--r--r--  1 root root 4096 May 14 16:06 time_in_state
  54     -r--r--r--  1 root root 4096 May 14 16:06 total_trans
  55     -r--r--r--  1 root root 4096 May 14 16:06 trans_table
  56
  57 - **reset**
  58
  59 Write-only attribute that can be used to reset the stat counters. This can be
  60 useful for evaluating system behaviour under different governors without the
  61 need for a reboot.
  62
  63 - **time_in_state**
  64
  65 This gives the amount of time spent in each of the frequencies supported by
  66 this CPU. The cat output will have "<frequency> <time>" pair in each line, which
  67 will mean this CPU spent <time> usertime units of time at <frequency>. Output
  68 will have one line for each of the supported frequencies. usertime units here
  69 is 10mS (similar to other time exported in /proc).
  70
  71 ::
  72
  73     <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state
  74     3600000 2089
  75     3400000 136
  76     3200000 34
  77     3000000 67
  78     2800000 172488
  79
  80
  81 - **total_trans**
  82
  83 This gives the total number of frequency transitions on this CPU. The cat
  84 output will have a single count which is the total number of frequency
  85 transitions.
  86
  87 ::
  88
  89     <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
  90     20
  91
  92 - **trans_table**
  93
  94 This will give a fine grained information about all the CPU frequency
  95 transitions. The cat output here is a two dimensional matrix, where an entry
  96 <i,j> (row i, column j) represents the count of number of transitions from
  97 Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
  98 which the driver has provided the frequency table initially to the cpufreq core
  99 and so can be sorted (ascending or descending) or unsorted.  The output here
 100 also contains the actual freq values for each row and column for better
 101 readability.
 102
 103 If the transition table is bigger than PAGE_SIZE, reading this will
 104 return an -EFBIG error.
 105
 106 ::
 107
 108     <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table
 109     From  :    To
 110             :   3600000   3400000   3200000   3000000   2800000
 111     3600000:         0         5         0         0         0
 112     3400000:         4         0         2         0         0
 113     3200000:         0         1         0         2         0
 114     3000000:         0         0         1         0         3
 115     2800000:         0         0         0         2         0
 116
 117 3. Configuring cpufreq-stats
 118 ============================
 119
 120 To configure cpufreq-stats in your kernel::
 121
 122         Config Main Menu
 123                 Power management options (ACPI, APM)  --->
 124                         CPU Frequency scaling  --->
 125                                 [*] CPU Frequency scaling
 126                                 [*]   CPU frequency translation statistics
 127
 128
 129 "CPU Frequency scaling" (CONFIG_CPU_FREQ) should be enabled to configure
 130 cpufreq-stats.
 131
 132 "CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT) provides the
 133 statistics which includes time_in_state, total_trans and trans_table.
 134
 135 Once this option is enabled and your CPU supports cpufrequency, you
 136 will be able to see the CPU frequency statistics in /sysfs.