1c460f972SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2c460f972SMauro Carvalho Chehab 3c460f972SMauro Carvalho Chehab============================================================= 4c460f972SMauro Carvalho ChehabGeneral description of the CPUFreq core and CPUFreq notifiers 5c460f972SMauro Carvalho Chehab============================================================= 6c460f972SMauro Carvalho Chehab 7c460f972SMauro Carvalho ChehabAuthors: 8c460f972SMauro Carvalho Chehab - Dominik Brodowski <linux@brodo.de> 9c460f972SMauro Carvalho Chehab - David Kimdon <dwhedon@debian.org> 10c460f972SMauro Carvalho Chehab - Rafael J. Wysocki <rafael.j.wysocki@intel.com> 11c460f972SMauro Carvalho Chehab - Viresh Kumar <viresh.kumar@linaro.org> 12c460f972SMauro Carvalho Chehab 13c460f972SMauro Carvalho Chehab.. Contents: 14c460f972SMauro Carvalho Chehab 15c460f972SMauro Carvalho Chehab 1. CPUFreq core and interfaces 16c460f972SMauro Carvalho Chehab 2. CPUFreq notifiers 17c460f972SMauro Carvalho Chehab 3. CPUFreq Table Generation with Operating Performance Point (OPP) 18c460f972SMauro Carvalho Chehab 19c460f972SMauro Carvalho Chehab1. General Information 20c460f972SMauro Carvalho Chehab====================== 21c460f972SMauro Carvalho Chehab 22c460f972SMauro Carvalho ChehabThe CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This 23c460f972SMauro Carvalho Chehabcpufreq code offers a standardized interface for the CPUFreq 24c460f972SMauro Carvalho Chehabarchitecture drivers (those pieces of code that do actual 25c460f972SMauro Carvalho Chehabfrequency transitions), as well as to "notifiers". These are device 26c460f972SMauro Carvalho Chehabdrivers or other part of the kernel that need to be informed of 27c460f972SMauro Carvalho Chehabpolicy changes (ex. thermal modules like ACPI) or of all 28c460f972SMauro Carvalho Chehabfrequency changes (ex. timing code) or even need to force certain 29c460f972SMauro Carvalho Chehabspeed limits (like LCD drivers on ARM architecture). Additionally, the 30c460f972SMauro Carvalho Chehabkernel "constant" loops_per_jiffy is updated on frequency changes 31c460f972SMauro Carvalho Chehabhere. 32c460f972SMauro Carvalho Chehab 33c460f972SMauro Carvalho ChehabReference counting of the cpufreq policies is done by cpufreq_cpu_get 34c460f972SMauro Carvalho Chehaband cpufreq_cpu_put, which make sure that the cpufreq driver is 35c460f972SMauro Carvalho Chehabcorrectly registered with the core, and will not be unloaded until 36c460f972SMauro Carvalho Chehabcpufreq_put_cpu is called. That also ensures that the respective cpufreq 37c460f972SMauro Carvalho Chehabpolicy doesn't get freed while being used. 38c460f972SMauro Carvalho Chehab 39c460f972SMauro Carvalho Chehab2. CPUFreq notifiers 40c460f972SMauro Carvalho Chehab==================== 41c460f972SMauro Carvalho Chehab 42c460f972SMauro Carvalho ChehabCPUFreq notifiers conform to the standard kernel notifier interface. 43c460f972SMauro Carvalho ChehabSee linux/include/linux/notifier.h for details on notifiers. 44c460f972SMauro Carvalho Chehab 45c460f972SMauro Carvalho ChehabThere are two different CPUFreq notifiers - policy notifiers and 46c460f972SMauro Carvalho Chehabtransition notifiers. 47c460f972SMauro Carvalho Chehab 48c460f972SMauro Carvalho Chehab 49c460f972SMauro Carvalho Chehab2.1 CPUFreq policy notifiers 50c460f972SMauro Carvalho Chehab---------------------------- 51c460f972SMauro Carvalho Chehab 52c460f972SMauro Carvalho ChehabThese are notified when a new policy is created or removed. 53c460f972SMauro Carvalho Chehab 54c460f972SMauro Carvalho ChehabThe phase is specified in the second argument to the notifier. The phase is 55c460f972SMauro Carvalho ChehabCPUFREQ_CREATE_POLICY when the policy is first created and it is 56c460f972SMauro Carvalho ChehabCPUFREQ_REMOVE_POLICY when the policy is removed. 57c460f972SMauro Carvalho Chehab 58c460f972SMauro Carvalho ChehabThe third argument, a ``void *pointer``, points to a struct cpufreq_policy 59c460f972SMauro Carvalho Chehabconsisting of several values, including min, max (the lower and upper 60c460f972SMauro Carvalho Chehabfrequencies (in kHz) of the new policy). 61c460f972SMauro Carvalho Chehab 62c460f972SMauro Carvalho Chehab 63c460f972SMauro Carvalho Chehab2.2 CPUFreq transition notifiers 64c460f972SMauro Carvalho Chehab-------------------------------- 65c460f972SMauro Carvalho Chehab 66c460f972SMauro Carvalho ChehabThese are notified twice for each online CPU in the policy, when the 67c460f972SMauro Carvalho ChehabCPUfreq driver switches the CPU core frequency and this change has no 68c460f972SMauro Carvalho Chehabany external implications. 69c460f972SMauro Carvalho Chehab 70c460f972SMauro Carvalho ChehabThe second argument specifies the phase - CPUFREQ_PRECHANGE or 71c460f972SMauro Carvalho ChehabCPUFREQ_POSTCHANGE. 72c460f972SMauro Carvalho Chehab 73c460f972SMauro Carvalho ChehabThe third argument is a struct cpufreq_freqs with the following 74c460f972SMauro Carvalho Chehabvalues: 75c460f972SMauro Carvalho Chehab 76*a15b8cd7STang Yizhou====== ====================================== 77*a15b8cd7STang Yizhoupolicy a pointer to the struct cpufreq_policy 78c460f972SMauro Carvalho Chehabold old frequency 79c460f972SMauro Carvalho Chehabnew new frequency 80c460f972SMauro Carvalho Chehabflags flags of the cpufreq driver 81*a15b8cd7STang Yizhou====== ====================================== 82c460f972SMauro Carvalho Chehab 83c460f972SMauro Carvalho Chehab3. CPUFreq Table Generation with Operating Performance Point (OPP) 84c460f972SMauro Carvalho Chehab================================================================== 85c460f972SMauro Carvalho ChehabFor details about OPP, see Documentation/power/opp.rst 86c460f972SMauro Carvalho Chehab 87c460f972SMauro Carvalho Chehabdev_pm_opp_init_cpufreq_table - 88c460f972SMauro Carvalho Chehab This function provides a ready to use conversion routine to translate 89c460f972SMauro Carvalho Chehab the OPP layer's internal information about the available frequencies 90c460f972SMauro Carvalho Chehab into a format readily providable to cpufreq. 91c460f972SMauro Carvalho Chehab 92c460f972SMauro Carvalho Chehab .. Warning:: 93c460f972SMauro Carvalho Chehab 94c460f972SMauro Carvalho Chehab Do not use this function in interrupt context. 95c460f972SMauro Carvalho Chehab 96c460f972SMauro Carvalho Chehab Example:: 97c460f972SMauro Carvalho Chehab 98c460f972SMauro Carvalho Chehab soc_pm_init() 99c460f972SMauro Carvalho Chehab { 100c460f972SMauro Carvalho Chehab /* Do things */ 101c460f972SMauro Carvalho Chehab r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); 102c460f972SMauro Carvalho Chehab if (!r) 103c460f972SMauro Carvalho Chehab policy->freq_table = freq_table; 104c460f972SMauro Carvalho Chehab /* Do other things */ 105c460f972SMauro Carvalho Chehab } 106c460f972SMauro Carvalho Chehab 107c460f972SMauro Carvalho Chehab .. note:: 108c460f972SMauro Carvalho Chehab 109c460f972SMauro Carvalho Chehab This function is available only if CONFIG_CPU_FREQ is enabled in 110c460f972SMauro Carvalho Chehab addition to CONFIG_PM_OPP. 111c460f972SMauro Carvalho Chehab 112c460f972SMauro Carvalho Chehabdev_pm_opp_free_cpufreq_table 113c460f972SMauro Carvalho Chehab Free up the table allocated by dev_pm_opp_init_cpufreq_table 114