Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) How to Implement a new CPUFreq Processor Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) Authors:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) 	- Dominik Brodowski  <linux@brodo.de>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 	- Rafael J. Wysocki <rafael.j.wysocki@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 	- Viresh Kumar <viresh.kumar@linaro.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) .. Contents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16)    1.   What To Do?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17)    1.1  Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18)    1.2  Per-CPU Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19)    1.3  verify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20)    1.4  target/target_index or setpolicy?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21)    1.5  target/target_index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22)    1.6  setpolicy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23)    1.7  get_intermediate and target_intermediate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24)    2.   Frequency Table Helpers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) 1. What To Do?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) So, you just got a brand-new CPU / chipset with datasheets and want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) add cpufreq support for this CPU / chipset? Great. Here are some hints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) on what is necessary:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) 1.1 Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) First of all, in an __initcall level 7 (module_init()) or later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) function check whether this kernel runs on the right CPU and the right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) chipset. If so, register a struct cpufreq_driver with the CPUfreq core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) using cpufreq_register_driver()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) What shall this struct cpufreq_driver contain?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46)  .name - The name of this driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48)  .init - A pointer to the per-policy initialization function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50)  .verify - A pointer to a "verification" function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)  .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53)  below on the differences.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) And optionally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57)  .flags - Hints for the cpufreq core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59)  .driver_data - cpufreq driver specific data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61)  .resolve_freq - Returns the most appropriate frequency for a target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62)  frequency. Doesn't change the frequency though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64)  .get_intermediate and target_intermediate - Used to switch to stable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65)  frequency while changing CPU frequency.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67)  .get - Returns current frequency of the CPU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69)  .bios_limit - Returns HW/BIOS max frequency limitations for the CPU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71)  .exit - A pointer to a per-policy cleanup function called during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72)  CPU_POST_DEAD phase of cpu hotplug process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74)  .stop_cpu - A pointer to a per-policy stop function called during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75)  CPU_DOWN_PREPARE phase of cpu hotplug process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77)  .suspend - A pointer to a per-policy suspend function which is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)  with interrupts disabled and _after_ the governor is stopped for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79)  policy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81)  .resume - A pointer to a per-policy resume function which is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82)  with interrupts disabled and _before_ the governor is started again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84)  .ready - A pointer to a per-policy ready function which is called after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85)  the policy is fully initialized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87)  .attr - A pointer to a NULL-terminated list of "struct freq_attr" which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88)  allow to export values to sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90)  .boost_enabled - If set, boost frequencies are enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92)  .set_boost - A pointer to a per-policy function to enable/disable boost
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93)  frequencies.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 1.2 Per-CPU Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) Whenever a new CPU is registered with the device model, or after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) cpufreq driver registers itself, the per-policy initialization function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) cpufreq_driver.init is called if no cpufreq policy existed for the CPU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Note that the .init() and .exit() routines are called only once for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) policy and not for each CPU managed by the policy. It takes a ``struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) cpufreq_policy *policy`` as argument. What to do now?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) If necessary, activate the CPUfreq support on your CPU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) Then, the driver must fill in the following values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) +-----------------------------------+--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) |policy->cpuinfo.min_freq _and_	    |					   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) |policy->cpuinfo.max_freq	    | the minimum and maximum frequency	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) |				    | (in kHz) which is supported by	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) |				    | this CPU				   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) +-----------------------------------+--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) |policy->cpuinfo.transition_latency | the time it takes on this CPU to	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) |				    | switch between two frequencies in	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) |				    | nanoseconds (if appropriate, else	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) |				    | specify CPUFREQ_ETERNAL)		   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) +-----------------------------------+--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) |policy->cur			    | The current operating frequency of   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) |				    | this CPU (if appropriate)		   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) +-----------------------------------+--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) |policy->min,			    |					   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) |policy->max,			    |					   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) |policy->policy and, if necessary,  |					   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) |policy->governor		    | must contain the "default policy" for|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) |				    | this CPU. A few moments later,       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) |				    | cpufreq_driver.verify and either     |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) |				    | cpufreq_driver.setpolicy or          |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) |				    | cpufreq_driver.target/target_index is|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) |				    | called with these values.		   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) +-----------------------------------+--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) |policy->cpus			    | Update this with the masks of the	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) |				    | (online + offline) CPUs that do DVFS |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) |				    | along with this CPU (i.e.  that share|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) |				    | clock/voltage rails with it).	   |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) +-----------------------------------+--------------------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) frequency table helpers might be helpful. See the section 2 for more information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) on them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 1.3 verify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) When the user decides a new policy (consisting of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) "policy,governor,min,max") shall be set, this policy must be validated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) so that incompatible values can be corrected. For verifying these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) values cpufreq_verify_within_limits(``struct cpufreq_policy *policy``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) ``unsigned int min_freq``, ``unsigned int max_freq``) function might be helpful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) See section 2 for details on frequency table helpers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) You need to make sure that at least one valid frequency (or operating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) range) is within policy->min and policy->max. If necessary, increase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) policy->max first, and only if this is no solution, decrease policy->min.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) 1.4 target or target_index or setpolicy or fast_switch?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) -------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) Most cpufreq drivers or even most cpu frequency scaling algorithms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) only allow the CPU frequency to be set to predefined fixed values. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) these, you use the ->target(), ->target_index() or ->fast_switch()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Some cpufreq capable processors switch the frequency between certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) limits on their own. These shall use the ->setpolicy() callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 1.5. target/target_index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) The target_index call has two arguments: ``struct cpufreq_policy *policy``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) and ``unsigned int`` index (into the exposed frequency table).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) The CPUfreq driver must set the new frequency when called here. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) actual frequency must be determined by freq_table[index].frequency.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) It should always restore to earlier frequency (i.e. policy->restore_freq) in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) case of errors, even if we switched to intermediate frequency earlier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) Deprecated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) The target call has three arguments: ``struct cpufreq_policy *policy``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) unsigned int target_frequency, unsigned int relation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) The CPUfreq driver must set the new frequency when called here. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) actual frequency must be determined using the following rules:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) - keep close to "target_freq"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) - policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) - if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)   target_freq. ("L for lowest, but no lower than")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) - if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)   target_freq. ("H for highest, but no higher than")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) Here again the frequency table helper might assist you - see section 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) 1.6. fast_switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) This function is used for frequency switching from scheduler's context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Not all drivers are expected to implement it, as sleeping from within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) this callback isn't allowed. This callback must be highly optimized to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) do switching as fast as possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) This function has two arguments: ``struct cpufreq_policy *policy`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) ``unsigned int target_frequency``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) 1.7 setpolicy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) The setpolicy call only takes a ``struct cpufreq_policy *policy`` as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) argument. You need to set the lower limit of the in-processor or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) in-chipset dynamic frequency switching to policy->min, the upper limit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) to policy->max, and -if supported- select a performance-oriented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) the reference implementation in drivers/cpufreq/longrun.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 1.8 get_intermediate and target_intermediate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) get_intermediate should return a stable intermediate frequency platform wants to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) switch to, and target_intermediate() should set CPU to that frequency, before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) jumping to the frequency corresponding to 'index'. Core will take care of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) sending notifications and driver doesn't have to handle them in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) target_intermediate() or target_index().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) Drivers can return '0' from get_intermediate() in case they don't wish to switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) to intermediate frequency for some target frequency. In that case core will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) directly call ->target_index().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) NOTE: ->target_index() should restore to policy->restore_freq in case of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) failures as core would send notifications for that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) 2. Frequency Table Helpers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) As most cpufreq processors only allow for being set to a few specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) frequencies, a "frequency table" with some functions might assist in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) some work of the processor driver. Such a "frequency table" consists of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) an array of struct cpufreq_frequency_table entries, with driver specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) values in "driver_data", the corresponding frequency in "frequency" and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) flags set. At the end of the table, you need to add a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) And if you want to skip one entry in the table, set the frequency to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) CPUFREQ_ENTRY_INVALID. The entries don't need to be in sorted in any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) particular order, but if they are cpufreq core will do DVFS a bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) quickly for them as search for best match is faster.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) The cpufreq table is verified automatically by the core if the policy contains a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) valid pointer in its policy->freq_table field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) cpufreq_frequency_table_verify() assures that at least one valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) frequency is within policy->min and policy->max, and all other criteria
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) are met. This is helpful for the ->verify call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) cpufreq_frequency_table_target() is the corresponding frequency table
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) helper for the ->target stage. Just pass the values to this function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) and this function returns the of the frequency table entry which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) contains the frequency the CPU shall be set to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) The following macros can be used as iterators over cpufreq_frequency_table:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) table.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) excluding CPUFREQ_ENTRY_INVALID frequencies.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) Use arguments "pos" - a ``cpufreq_frequency_table *`` as a loop cursor and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) "table" - the ``cpufreq_frequency_table *`` you want to iterate over.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) 	struct cpufreq_frequency_table *pos, *driver_freq_table;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) 	cpufreq_for_each_entry(pos, driver_freq_table) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) 		/* Do something with pos */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 		pos->frequency = ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) 	}
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) If you need to work with the position of pos within driver_freq_table,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) do not subtract the pointers, as it is quite costly. Instead, use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) macros cpufreq_for_each_entry_idx() and cpufreq_for_each_valid_entry_idx().