[PATCH] cpufreq-stats driver documentation

     CPU frequency and voltage scaling statictics in the Linux(TM) kernel

             L i n u x    c p u f r e q - s t a t s   d r i v e r

                       - information for users -

             Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>

Contents

1. Introduction

2. Statistics Provided (with example)

3. Configuring cpufreq-stats

1. Introduction

cpufreq-stats is a driver that provices CPU frequency statistics for each CPU.

This statistics is provided in /sysfs as a bunch of read_only interfaces. This

interface (when configured) will appear in a seperate directory under cpufreq

in /sysfs (<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/) for each CPU.

Various statistics will form read_only files under this directory.

This driver is designed to be independent of any particular cpufreq_driver

that may be running on your CPU. So, it will work with any cpufreq_driver.

2. Statistics Provided (with example)

cpufreq stats provides following statistics (explained in detail below).

-  time_in_state

-  total_trans

-  trans_table

All the statistics will be from the time the stats driver has been inserted 

to the time when a read of a particular statistic is done. Obviously, stats 

driver will not have any information about the the frequcny transitions before

the stats driver insertion.

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l

total 0

drwxr-xr-x  2 root root    0 May 14 16:06 .

drwxr-xr-x  3 root root    0 May 14 15:58 ..

-r--r--r--  1 root root 4096 May 14 16:06 time_in_state

-r--r--r--  1 root root 4096 May 14 16:06 total_trans

-r--r--r--  1 root root 4096 May 14 16:06 trans_table

--------------------------------------------------------------------------------

-  time_in_state

This gives the amount of time spent in each of the frequencies supported by

this CPU. The cat output will have "<frequency> <time>" pair in each line, which

will mean this CPU spent <time> usertime units of time at <frequency>. Output

will have one line for each of the supported freuencies. usertime units here 

is 10mS (similar to other time exported in /proc).

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state 

3600000 2089

3400000 136

3200000 34

3000000 67

2800000 172488

--------------------------------------------------------------------------------

-  total_trans

This gives the total number of frequency transitions on this CPU. The cat 

output will have a single count which is the total number of frequency

transitions.

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans

20

--------------------------------------------------------------------------------

-  trans_table

This will give a fine grained information about all the CPU frequency

transitions. The cat output here is a two dimensional matrix, where an entry

<i,j> (row i, column j) represents the count of number of transitions from 

Freq_i to Freq_j. Freq_i is in descending order with increasing rows and 

Freq_j is in descending order with increasing columns. The output here also 

contains the actual freq values for each row and column for better readability.

--------------------------------------------------------------------------------

<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table

   From  :    To

         :   3600000   3400000   3200000   3000000   2800000 

  3600000:         0         5         0         0         0 

  3400000:         4         0         2         0         0 

  3200000:         0         1         0         2         0 

  3000000:         0         0         1         0         3 

  2800000:         0         0         0         2         0 

--------------------------------------------------------------------------------

3. Configuring cpufreq-stats

To configure cpufreq-stats in your kernel

Config Main Menu

	Power management options (ACPI, APM)  --->

		CPU Frequency scaling  --->

			[*] CPU Frequency scaling

			<*>   CPU frequency translation statistics 

			[*]     CPU frequency translation statistics details

"CPU Frequency scaling" (CONFIG_CPU_FREQ) should be enabled to configure

cpufreq-stats.

"CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT) provides the

basic statistics which includes time_in_state and total_trans.

"CPU frequency translation statistics details" (CONFIG_CPU_FREQ_STAT_DETAILS)

provides fine grained cpufreq stats by trans_table. The reason for having a

seperate config option for trans_table is:

- trans_table goes against the traditional /sysfs rule of one value per

  interface. It provides a whole bunch of value in a 2 dimensional matrix

  form.

Once these two options are enabled and your CPU supports cpufrequency, you

will be able to see the CPU frequency statistics in /sysfs.