docs: cpu-freq: convert cpu-drivers.txt to ReST

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

.. SPDX-License-Identifier: GPL-2.0

===============================================

How to Implement a new CPUFreq Processor Driver

===============================================

		         L i n u x    C P U F r e q

Authors:

			   C P U   D r i v e r s 

		       - information for developers -

	- Dominik Brodowski  <linux@brodo.de>

	- Rafael J. Wysocki <rafael.j.wysocki@intel.com>

	- Viresh Kumar <viresh.kumar@linaro.org>

.. Contents

		    Dominik Brodowski  <linux@brodo.de>

		Rafael J. Wysocki <rafael.j.wysocki@intel.com>

		   Viresh Kumar <viresh.kumar@linaro.org>

   Clock scaling allows you to change the clock speed of the CPUs on the

    fly. This is a nice method to save battery power, because the lower

            the clock speed, the less power the CPU consumes.

Contents:

---------

   1.   What To Do?

   1.1  Initialization

   1.2  Per-CPU Initialization

cpufreq driver registers itself, the per-policy initialization function

cpufreq_driver.init is called if no cpufreq policy existed for the CPU.

Note that the .init() and .exit() routines are called only once for the

policy and not for each CPU managed by the policy. It takes a struct

cpufreq_policy *policy as argument. What to do now?

policy and not for each CPU managed by the policy. It takes a ``struct

cpufreq_policy *policy`` as argument. What to do now?

If necessary, activate the CPUfreq support on your CPU.

Then, the driver must fill in the following values:

policy->cpuinfo.min_freq _and_

policy->cpuinfo.max_freq -	the minimum and maximum frequency 

				(in kHz) which is supported by 

				this CPU

policy->cpuinfo.transition_latency   the time it takes on this CPU to

				switch between two frequencies in

				nanoseconds (if appropriate, else

				specify CPUFREQ_ETERNAL)

policy->cur			The current operating frequency of

				this CPU (if appropriate)

policy->min, 

policy->max, 

policy->policy and, if necessary,

policy->governor		must contain the "default policy" for

				this CPU. A few moments later,

				cpufreq_driver.verify and either

				cpufreq_driver.setpolicy or

				cpufreq_driver.target/target_index is called

				with these values.

policy->cpus			Update this with the masks of the

				(online + offline) CPUs that do DVFS

				along with this CPU (i.e.  that share

				clock/voltage rails with it).

+-----------------------------------+--------------------------------------+

|policy->cpuinfo.min_freq _and_	    |					   |

|policy->cpuinfo.max_freq	    | the minimum and maximum frequency	   |

|				    | (in kHz) which is supported by	   |

|				    | this CPU				   |

+-----------------------------------+--------------------------------------+

|policy->cpuinfo.transition_latency | the time it takes on this CPU to	   |

|				    | switch between two frequencies in	   |

|				    | nanoseconds (if appropriate, else	   |

|				    | specify CPUFREQ_ETERNAL)		   |

+-----------------------------------+--------------------------------------+

|policy->cur			    | The current operating frequency of   |

|				    | this CPU (if appropriate)		   |

+-----------------------------------+--------------------------------------+

|policy->min,			    |					   |

|policy->max,			    |					   |

|policy->policy and, if necessary,  |					   |

|policy->governor		    | must contain the "default policy" for|

|				    | this CPU. A few moments later,       |

|				    | cpufreq_driver.verify and either     |

|				    | cpufreq_driver.setpolicy or          |

|				    | cpufreq_driver.target/target_index is|

|				    | called with these values.		   |

+-----------------------------------+--------------------------------------+

|policy->cpus			    | Update this with the masks of the	   |

|				    | (online + offline) CPUs that do DVFS |

|				    | along with this CPU (i.e.  that share|

|				    | clock/voltage rails with it).	   |

+-----------------------------------+--------------------------------------+

For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the

frequency table helpers might be helpful. See the section 2 for more information

When the user decides a new policy (consisting of

"policy,governor,min,max") shall be set, this policy must be validated

so that incompatible values can be corrected. For verifying these

values cpufreq_verify_within_limits(struct cpufreq_policy *policy,

unsigned int min_freq, unsigned int max_freq) function might be helpful.

values cpufreq_verify_within_limits(``struct cpufreq_policy *policy``,

``unsigned int min_freq``, ``unsigned int max_freq``) function might be helpful.

See section 2 for details on frequency table helpers.

You need to make sure that at least one valid frequency (or operating

1.5. target/target_index

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

The target_index call has two arguments: struct cpufreq_policy *policy,

and unsigned int index (into the exposed frequency table).

The target_index call has two arguments: ``struct cpufreq_policy *policy``,

and ``unsigned int`` index (into the exposed frequency table).

The CPUfreq driver must set the new frequency when called here. The

actual frequency must be determined by freq_table[index].frequency.

It should always restore to earlier frequency (i.e. policy->restore_freq) in

case of errors, even if we switched to intermediate frequency earlier.

Deprecated:

Deprecated

----------

The target call has three arguments: struct cpufreq_policy *policy,

The target call has three arguments: ``struct cpufreq_policy *policy``,

unsigned int target_frequency, unsigned int relation.

The CPUfreq driver must set the new frequency when called here. The

this callback isn't allowed. This callback must be highly optimized to

do switching as fast as possible.

This function has two arguments: struct cpufreq_policy *policy and

unsigned int target_frequency.

This function has two arguments: ``struct cpufreq_policy *policy`` and

``unsigned int target_frequency``.

1.7 setpolicy

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

The setpolicy call only takes a struct cpufreq_policy *policy as

The setpolicy call only takes a ``struct cpufreq_policy *policy`` as

argument. You need to set the lower limit of the in-processor or

in-chipset dynamic frequency switching to policy->min, the upper limit

to policy->max, and -if supported- select a performance-oriented

cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,

excluding CPUFREQ_ENTRY_INVALID frequencies.

Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and

"table" - the cpufreq_frequency_table * you want to iterate over.

Use arguments "pos" - a ``cpufreq_frequency_table *`` as a loop cursor and

"table" - the ``cpufreq_frequency_table *`` you want to iterate over.

For example:

For example::

	struct cpufreq_frequency_table *pos, *driver_freq_table;

   :maxdepth: 1

   core

   cpu-drivers

Mailing List

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