0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =============================================================
0004 General description of the CPUFreq core and CPUFreq notifiers
0005 =============================================================
0006
0007 Authors:
0008 - Dominik Brodowski <linux@brodo.de>
0009 - David Kimdon <dwhedon@debian.org>
0010 - Rafael J. Wysocki <rafael.j.wysocki@intel.com>
0011 - Viresh Kumar <viresh.kumar@linaro.org>
0012
0013 .. Contents:
0014
0015 1. CPUFreq core and interfaces
0016 2. CPUFreq notifiers
0017 3. CPUFreq Table Generation with Operating Performance Point (OPP)
0018
0019 1. General Information
0020 ======================
0021
0022 The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This
0023 cpufreq code offers a standardized interface for the CPUFreq
0024 architecture drivers (those pieces of code that do actual
0025 frequency transitions), as well as to "notifiers". These are device
0026 drivers or other part of the kernel that need to be informed of
0027 policy changes (ex. thermal modules like ACPI) or of all
0028 frequency changes (ex. timing code) or even need to force certain
0029 speed limits (like LCD drivers on ARM architecture). Additionally, the
0030 kernel "constant" loops_per_jiffy is updated on frequency changes
0031 here.
0032
0033 Reference counting of the cpufreq policies is done by cpufreq_cpu_get
0034 and cpufreq_cpu_put, which make sure that the cpufreq driver is
0035 correctly registered with the core, and will not be unloaded until
0036 cpufreq_put_cpu is called. That also ensures that the respective cpufreq
0037 policy doesn't get freed while being used.
0038
0039 2. CPUFreq notifiers
0040 ====================
0041
0042 CPUFreq notifiers conform to the standard kernel notifier interface.
0043 See linux/include/linux/notifier.h for details on notifiers.
0044
0045 There are two different CPUFreq notifiers - policy notifiers and
0046 transition notifiers.
0047
0048
0049 2.1 CPUFreq policy notifiers
0050 ----------------------------
0051
0052 These are notified when a new policy is created or removed.
0053
0054 The phase is specified in the second argument to the notifier. The phase is
0055 CPUFREQ_CREATE_POLICY when the policy is first created and it is
0056 CPUFREQ_REMOVE_POLICY when the policy is removed.
0057
0058 The third argument, a ``void *pointer``, points to a struct cpufreq_policy
0059 consisting of several values, including min, max (the lower and upper
0060 frequencies (in kHz) of the new policy).
0061
0062
0063 2.2 CPUFreq transition notifiers
0064 --------------------------------
0065
0066 These are notified twice for each online CPU in the policy, when the
0067 CPUfreq driver switches the CPU core frequency and this change has no
0068 any external implications.
0069
0070 The second argument specifies the phase - CPUFREQ_PRECHANGE or
0071 CPUFREQ_POSTCHANGE.
0072
0073 The third argument is a struct cpufreq_freqs with the following
0074 values:
0075
0076 ====== ======================================
0077 policy a pointer to the struct cpufreq_policy
0078 old old frequency
0079 new new frequency
0080 flags flags of the cpufreq driver
0081 ====== ======================================
0082
0083 3. CPUFreq Table Generation with Operating Performance Point (OPP)
0084 ==================================================================
0085 For details about OPP, see Documentation/power/opp.rst
0086
0087 dev_pm_opp_init_cpufreq_table -
0088 This function provides a ready to use conversion routine to translate
0089 the OPP layer's internal information about the available frequencies
0090 into a format readily providable to cpufreq.
0091
0092 .. Warning::
0093
0094 Do not use this function in interrupt context.
0095
0096 Example::
0097
0098 soc_pm_init()
0099 {
0100 /* Do things */
0101 r = dev_pm_opp_init_cpufreq_table(dev, &freq_table);
0102 if (!r)
0103 policy->freq_table = freq_table;
0104 /* Do other things */
0105 }
0106
0107 .. note::
0108
0109 This function is available only if CONFIG_CPU_FREQ is enabled in
0110 addition to CONFIG_PM_OPP.
0111
0112 dev_pm_opp_free_cpufreq_table
0113 Free up the table allocated by dev_pm_opp_init_cpufreq_table
