From 8f92058987a1e3ec851218420ac1ef554aca41fe Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 3 Mar 2020 14:52:05 +0100 Subject: docs: cpu-freq: convert cpu-drivers.txt to ReST - 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 Signed-off-by: Rafael J. Wysocki --- Documentation/cpu-freq/cpu-drivers.rst | 292 ++++++++++++++++++++++++++++++++ Documentation/cpu-freq/cpu-drivers.txt | 295 --------------------------------- Documentation/cpu-freq/index.rst | 1 + 3 files changed, 293 insertions(+), 295 deletions(-) create mode 100644 Documentation/cpu-freq/cpu-drivers.rst delete mode 100644 Documentation/cpu-freq/cpu-drivers.txt diff --git a/Documentation/cpu-freq/cpu-drivers.rst b/Documentation/cpu-freq/cpu-drivers.rst new file mode 100644 index 000000000000..a697278ce190 --- /dev/null +++ b/Documentation/cpu-freq/cpu-drivers.rst @@ -0,0 +1,292 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================== +How to Implement a new CPUFreq Processor Driver +=============================================== + +Authors: + + + - Dominik Brodowski + - Rafael J. Wysocki + - Viresh Kumar + +.. 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? +============== + +So, you just got a brand-new CPU / chipset with datasheets and want to +add cpufreq support for this CPU / chipset? Great. Here are some hints +on what is necessary: + + +1.1 Initialization +------------------ + +First of all, in an __initcall level 7 (module_init()) or later +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? + + .name - The name of this driver. + + .init - A pointer to the per-policy initialization function. + + .verify - A pointer to a "verification" function. + + .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See + below on the differences. + +And optionally + + .flags - Hints for the cpufreq core. + + .driver_data - cpufreq driver specific data. + + .resolve_freq - Returns the most appropriate frequency for a target + frequency. Doesn't change the frequency though. + + .get_intermediate and target_intermediate - Used to switch to stable + frequency while changing CPU frequency. + + .get - Returns current frequency of the CPU. + + .bios_limit - Returns HW/BIOS max frequency limitations for the CPU. + + .exit - A pointer to a per-policy cleanup function called during + CPU_POST_DEAD phase of cpu hotplug process. + + .stop_cpu - A pointer to a per-policy stop function called during + CPU_DOWN_PREPARE phase of cpu hotplug process. + + .suspend - A pointer to a per-policy suspend function which is called + with interrupts disabled and _after_ the governor is stopped for the + policy. + + .resume - A pointer to a per-policy resume function which is called + with interrupts disabled and _before_ the governor is started again. + + .ready - A pointer to a per-policy ready function which is called after + the policy is fully initialized. + + .attr - A pointer to a NULL-terminated list of "struct freq_attr" which + allow to export values to sysfs. + + .boost_enabled - If set, boost frequencies are enabled. + + .set_boost - A pointer to a per-policy function to enable/disable boost + frequencies. + + +1.2 Per-CPU Initialization +-------------------------- + +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? + +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). | ++-----------------------------------+--------------------------------------+ + +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 +on them. + + +1.3 verify +---------- + +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. +See section 2 for details on frequency table helpers. + +You need to make sure that at least one valid frequency (or operating +range) is within policy->min and policy->max. If necessary, increase +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 +only allow the CPU frequency to be set to predefined fixed values. For +these, you use the ->target(), ->target_index() or ->fast_switch() +callbacks. + +Some cpufreq capable processors switch the frequency between certain +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 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 +---------- +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 +actual frequency must be determined using the following rules: + +- keep close to "target_freq" +- policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!) +- if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal + target_freq. ("L for lowest, but no lower than") +- if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal + target_freq. ("H for highest, but no higher than") + +Here again the frequency table helper might assist you - see section 2 +for details. + +1.6. fast_switch +---------------- + +This function is used for frequency switching from scheduler's context. +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``. + + +1.7 setpolicy +------------- + +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 +setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a +powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check +the reference implementation in drivers/cpufreq/longrun.c + +1.8 get_intermediate and target_intermediate +-------------------------------------------- + +Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset. + +get_intermediate should return a stable intermediate frequency platform wants to +switch to, and target_intermediate() should set CPU to that frequency, before +jumping to the frequency corresponding to 'index'. Core will take care of +sending notifications and driver doesn't have to handle them in +target_intermediate() or target_index(). + +Drivers can return '0' from get_intermediate() in case they don't wish to switch +to intermediate frequency for some target frequency. In that case core will +directly call ->target_index(). + +NOTE: ->target_index() should restore to policy->restore_freq in case of +failures as core would send notifications for that. + + +2. Frequency Table Helpers +========================== + +As most cpufreq processors only allow for being set to a few specific +frequencies, a "frequency table" with some functions might assist in +some work of the processor driver. Such a "frequency table" consists of +an array of struct cpufreq_frequency_table entries, with driver specific +values in "driver_data", the corresponding frequency in "frequency" and +flags set. At the end of the table, you need to add a +cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END. +And if you want to skip one entry in the table, set the frequency to +CPUFREQ_ENTRY_INVALID. The entries don't need to be in sorted in any +particular order, but if they are cpufreq core will do DVFS a bit +quickly for them as search for best match is faster. + +The cpufreq table is verified automatically by the core if the policy contains a +valid pointer in its policy->freq_table field. + +cpufreq_frequency_table_verify() assures that at least one valid +frequency is within policy->min and policy->max, and all other criteria +are met. This is helpful for the ->verify call. + +cpufreq_frequency_table_target() is the corresponding frequency table +helper for the ->target stage. Just pass the values to this function, +and this function returns the of the frequency table entry which +contains the frequency the CPU shall be set to. + +The following macros can be used as iterators over cpufreq_frequency_table: + +cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency +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. + +For example:: + + struct cpufreq_frequency_table *pos, *driver_freq_table; + + cpufreq_for_each_entry(pos, driver_freq_table) { + /* Do something with pos */ + pos->frequency = ... + } + +If you need to work with the position of pos within driver_freq_table, +do not subtract the pointers, as it is quite costly. Instead, use the +macros cpufreq_for_each_entry_idx() and cpufreq_for_each_valid_entry_idx(). diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.txt deleted file mode 100644 index 6e353d00cdc6..000000000000 --- a/Documentation/cpu-freq/cpu-drivers.txt +++ /dev/null @@ -1,295 +0,0 @@ - CPU frequency and voltage scaling code in the Linux(TM) kernel - - - L i n u x C P U F r e q - - C P U D r i v e r s - - - information for developers - - - - Dominik Brodowski - Rafael J. Wysocki - Viresh Kumar - - - - 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? -============== - -So, you just got a brand-new CPU / chipset with datasheets and want to -add cpufreq support for this CPU / chipset? Great. Here are some hints -on what is necessary: - - -1.1 Initialization ------------------- - -First of all, in an __initcall level 7 (module_init()) or later -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? - - .name - The name of this driver. - - .init - A pointer to the per-policy initialization function. - - .verify - A pointer to a "verification" function. - - .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See - below on the differences. - -And optionally - - .flags - Hints for the cpufreq core. - - .driver_data - cpufreq driver specific data. - - .resolve_freq - Returns the most appropriate frequency for a target - frequency. Doesn't change the frequency though. - - .get_intermediate and target_intermediate - Used to switch to stable - frequency while changing CPU frequency. - - .get - Returns current frequency of the CPU. - - .bios_limit - Returns HW/BIOS max frequency limitations for the CPU. - - .exit - A pointer to a per-policy cleanup function called during - CPU_POST_DEAD phase of cpu hotplug process. - - .stop_cpu - A pointer to a per-policy stop function called during - CPU_DOWN_PREPARE phase of cpu hotplug process. - - .suspend - A pointer to a per-policy suspend function which is called - with interrupts disabled and _after_ the governor is stopped for the - policy. - - .resume - A pointer to a per-policy resume function which is called - with interrupts disabled and _before_ the governor is started again. - - .ready - A pointer to a per-policy ready function which is called after - the policy is fully initialized. - - .attr - A pointer to a NULL-terminated list of "struct freq_attr" which - allow to export values to sysfs. - - .boost_enabled - If set, boost frequencies are enabled. - - .set_boost - A pointer to a per-policy function to enable/disable boost - frequencies. - - -1.2 Per-CPU Initialization --------------------------- - -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? - -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). - -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 -on them. - - -1.3 verify ----------- - -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. -See section 2 for details on frequency table helpers. - -You need to make sure that at least one valid frequency (or operating -range) is within policy->min and policy->max. If necessary, increase -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 -only allow the CPU frequency to be set to predefined fixed values. For -these, you use the ->target(), ->target_index() or ->fast_switch() -callbacks. - -Some cpufreq capable processors switch the frequency between certain -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 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: ----------- -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 -actual frequency must be determined using the following rules: - -- keep close to "target_freq" -- policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!) -- if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal - target_freq. ("L for lowest, but no lower than") -- if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal - target_freq. ("H for highest, but no higher than") - -Here again the frequency table helper might assist you - see section 2 -for details. - -1.6. fast_switch ----------------- - -This function is used for frequency switching from scheduler's context. -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. - - -1.7 setpolicy -------------- - -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 -setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a -powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check -the reference implementation in drivers/cpufreq/longrun.c - -1.8 get_intermediate and target_intermediate --------------------------------------------- - -Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset. - -get_intermediate should return a stable intermediate frequency platform wants to -switch to, and target_intermediate() should set CPU to that frequency, before -jumping to the frequency corresponding to 'index'. Core will take care of -sending notifications and driver doesn't have to handle them in -target_intermediate() or target_index(). - -Drivers can return '0' from get_intermediate() in case they don't wish to switch -to intermediate frequency for some target frequency. In that case core will -directly call ->target_index(). - -NOTE: ->target_index() should restore to policy->restore_freq in case of -failures as core would send notifications for that. - - -2. Frequency Table Helpers -========================== - -As most cpufreq processors only allow for being set to a few specific -frequencies, a "frequency table" with some functions might assist in -some work of the processor driver. Such a "frequency table" consists of -an array of struct cpufreq_frequency_table entries, with driver specific -values in "driver_data", the corresponding frequency in "frequency" and -flags set. At the end of the table, you need to add a -cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END. -And if you want to skip one entry in the table, set the frequency to -CPUFREQ_ENTRY_INVALID. The entries don't need to be in sorted in any -particular order, but if they are cpufreq core will do DVFS a bit -quickly for them as search for best match is faster. - -The cpufreq table is verified automatically by the core if the policy contains a -valid pointer in its policy->freq_table field. - -cpufreq_frequency_table_verify() assures that at least one valid -frequency is within policy->min and policy->max, and all other criteria -are met. This is helpful for the ->verify call. - -cpufreq_frequency_table_target() is the corresponding frequency table -helper for the ->target stage. Just pass the values to this function, -and this function returns the of the frequency table entry which -contains the frequency the CPU shall be set to. - -The following macros can be used as iterators over cpufreq_frequency_table: - -cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency -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. - -For example: - - struct cpufreq_frequency_table *pos, *driver_freq_table; - - cpufreq_for_each_entry(pos, driver_freq_table) { - /* Do something with pos */ - pos->frequency = ... - } - -If you need to work with the position of pos within driver_freq_table, -do not subtract the pointers, as it is quite costly. Instead, use the -macros cpufreq_for_each_entry_idx() and cpufreq_for_each_valid_entry_idx(). diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst index 53501c58f41d..fcc58b2eee01 100644 --- a/Documentation/cpu-freq/index.rst +++ b/Documentation/cpu-freq/index.rst @@ -15,6 +15,7 @@ Author: Dominik Brodowski :maxdepth: 1 core + cpu-drivers Mailing List ------------ -- cgit v1.2.3-59-g8ed1b