Skip to content

Commit

Permalink
docs: cpu-freq: convert cpu-drivers.txt to ReST
Browse files Browse the repository at this point in the history 
- Add a SPDX header;
- Add a document title, based on the original contents of
  cpu-freq/index.txt;
- Use lists where needed;
- Comment out the existing text-only index;
- Adjust some title marks;
- Add table markups;
- Add notes markups;
- Mark literal blocks as such;
- use ``foo`` for literal texts;
- Some whitespace fixes and new line breaks;
- Add it to cpu-freq/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
  • Loading branch information
Mauro Carvalho Chehab authored and Rafael J. Wysocki committed Mar 5, 2020
1 parent c460f97 commit 8f92058
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 66 deletions.
129 changes: 63 additions & 66 deletions Documentation/cpu-freq/cpu-drivers.txt → Documentation/cpu-freq/cpu-drivers.rst
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,27 @@
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
1.3 verify
1.4 target/target_index or setpolicy?
1.5 target/target_index
1.6 setpolicy
1.7 get_intermediate and target_intermediate
2. Frequency Table Helpers
1. What To Do?
1.1 Initialization
1.2 Per-CPU Initialization
1.3 verify
1.4 target/target_index or setpolicy?
1.5 target/target_index
1.6 setpolicy
1.7 get_intermediate and target_intermediate
2. Frequency Table Helpers
Expand All @@ -49,7 +41,7 @@ function check whether this kernel runs on the right CPU and the right
chipset. If so, register a struct cpufreq_driver with the CPUfreq core
using cpufreq_register_driver()

What shall this struct cpufreq_driver contain?
What shall this struct cpufreq_driver contain?

.name - The name of this driver.

Expand Down Expand Up @@ -108,37 +100,42 @@ Whenever a new CPU is registered with the device model, or after the
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
Expand All @@ -151,8 +148,8 @@ on them.
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
Expand All @@ -163,7 +160,7 @@ policy->max first, and only if this is no solution, decrease policy->min.
1.4 target or target_index or setpolicy or fast_switch?
-------------------------------------------------------

Most cpufreq drivers or even most cpu frequency scaling algorithms
Most cpufreq drivers or even most cpu frequency scaling algorithms
only allow the CPU frequency to be set to predefined fixed values. For
these, you use the ->target(), ->target_index() or ->fast_switch()
callbacks.
Expand All @@ -175,18 +172,18 @@ limits on their own. These shall use the ->setpolicy() callback.
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
Expand All @@ -210,14 +207,14 @@ Not all drivers are expected to implement it, as sleeping from within
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
Expand Down Expand Up @@ -278,10 +275,10 @@ table.

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;

Expand Down
1 change: 1 addition & 0 deletions Documentation/cpu-freq/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Author: Dominik Brodowski <linux@brodo.de>
:maxdepth: 1

core
cpu-drivers

Mailing List
------------
Expand Down

0 comments on commit 8f92058

Please sign in to comment.