1.. SPDX-License-Identifier: GPL-2.0
2
3==========================================
4General Description of sysfs CPUFreq Stats
5==========================================
6
7information for users
8
9
10Author: 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
191. Introduction
20===============
21
22cpufreq-stats is a driver that provides CPU frequency statistics for each CPU.
23These statistics are provided in /sysfs as a bunch of read_only interfaces. This
24interface (when configured) will appear in a separate directory under cpufreq
25in /sysfs (<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/) for each CPU.
26Various statistics will form read_only files under this directory.
27
28This driver is designed to be independent of any particular cpufreq_driver
29that may be running on your CPU. So, it will work with any cpufreq_driver.
30
31
322. Statistics Provided (with example)
33=====================================
34
35cpufreq stats provides following statistics (explained in detail below).
36
37-  time_in_state
38-  total_trans
39-  trans_table
40
41All 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
43statistic is done. Obviously, stats driver will not have any information
44about 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
59Write-only attribute that can be used to reset the stat counters. This can be
60useful for evaluating system behaviour under different governors without the
61need for a reboot.
62
63- **time_in_state**
64
65This gives the amount of time spent in each of the frequencies supported by
66this CPU. The cat output will have "<frequency> <time>" pair in each line, which
67will mean this CPU spent <time> usertime units of time at <frequency>. Output
68will have one line for each of the supported frequencies. usertime units here
69is 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
83This gives the total number of frequency transitions on this CPU. The cat
84output will have a single count which is the total number of frequency
85transitions.
86
87::
88
89    <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans
90    20
91
92- **trans_table**
93
94This will give a fine grained information about all the CPU frequency
95transitions. 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
97Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in
98which the driver has provided the frequency table initially to the cpufreq core
99and so can be sorted (ascending or descending) or unsorted.  The output here
100also contains the actual freq values for each row and column for better
101readability.
102
103If the transition table is bigger than PAGE_SIZE, reading this will
104return 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
1173. Configuring cpufreq-stats
118============================
119
120To 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
130cpufreq-stats.
131
132"CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT) provides the
133statistics which includes time_in_state, total_trans and trans_table.
134
135Once this option is enabled and your CPU supports cpufrequency, you
136will be able to see the CPU frequency statistics in /sysfs.
137