diff options
Diffstat (limited to 'Documentation')
18 files changed, 576 insertions, 575 deletions
diff --git a/Documentation/admin-guide/pm/cpufreq_drivers.rst b/Documentation/admin-guide/pm/cpufreq_drivers.rst new file mode 100644 index 000000000000..9a134ae65803 --- /dev/null +++ b/Documentation/admin-guide/pm/cpufreq_drivers.rst @@ -0,0 +1,274 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= +Legacy Documentation of CPU Performance Scaling Drivers +======================================================= + +Included below are historic documents describing assorted +:doc:`CPU performance scaling <cpufreq>` drivers. They are reproduced verbatim, +with the original white space formatting and indentation preserved, except for +the added leading space character in every line of text. + + +AMD PowerNow! Drivers +===================== + +:: + + PowerNow! and Cool'n'Quiet are AMD names for frequency + management capabilities in AMD processors. As the hardware + implementation changes in new generations of the processors, + there is a different cpu-freq driver for each generation. + + Note that the driver's will not load on the "wrong" hardware, + so it is safe to try each driver in turn when in doubt as to + which is the correct driver. + + Note that the functionality to change frequency (and voltage) + is not available in all processors. The drivers will refuse + to load on processors without this capability. The capability + is detected with the cpuid instruction. + + The drivers use BIOS supplied tables to obtain frequency and + voltage information appropriate for a particular platform. + Frequency transitions will be unavailable if the BIOS does + not supply these tables. + + 6th Generation: powernow-k6 + + 7th Generation: powernow-k7: Athlon, Duron, Geode. + + 8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron. + Documentation on this functionality in 8th generation processors + is available in the "BIOS and Kernel Developer's Guide", publication + 26094, in chapter 9, available for download from www.amd.com. + + BIOS supplied data, for powernow-k7 and for powernow-k8, may be + from either the PSB table or from ACPI objects. The ACPI support + is only available if the kernel config sets CONFIG_ACPI_PROCESSOR. + The powernow-k8 driver will attempt to use ACPI if so configured, + and fall back to PST if that fails. + The powernow-k7 driver will try to use the PSB support first, and + fall back to ACPI if the PSB support fails. A module parameter, + acpi_force, is provided to force ACPI support to be used instead + of PSB support. + + +``cpufreq-nforce2`` +=================== + +:: + + The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms. + + This works better than on other platforms, because the FSB of the CPU + can be controlled independently from the PCI/AGP clock. + + The module has two options: + + fid: multiplier * 10 (for example 8.5 = 85) + min_fsb: minimum FSB + + If not set, fid is calculated from the current CPU speed and the FSB. + min_fsb defaults to FSB at boot time - 50 MHz. + + IMPORTANT: The available range is limited downwards! + Also the minimum available FSB can differ, for systems + booting with 200 MHz, 150 should always work. + + +``pcc-cpufreq`` +=============== + +:: + + /* + * pcc-cpufreq.txt - PCC interface documentation + * + * Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com> + * Copyright (C) 2009 Hewlett-Packard Development Company, L.P. + * Nagananda Chumbalkar <nagananda.chumbalkar@hp.com> + */ + + + Processor Clocking Control Driver + --------------------------------- + + Contents: + --------- + 1. Introduction + 1.1 PCC interface + 1.1.1 Get Average Frequency + 1.1.2 Set Desired Frequency + 1.2 Platforms affected + 2. Driver and /sys details + 2.1 scaling_available_frequencies + 2.2 cpuinfo_transition_latency + 2.3 cpuinfo_cur_freq + 2.4 related_cpus + 3. Caveats + + 1. Introduction: + ---------------- + Processor Clocking Control (PCC) is an interface between the platform + firmware and OSPM. It is a mechanism for coordinating processor + performance (ie: frequency) between the platform firmware and the OS. + + The PCC driver (pcc-cpufreq) allows OSPM to take advantage of the PCC + interface. + + OS utilizes the PCC interface to inform platform firmware what frequency the + OS wants for a logical processor. The platform firmware attempts to achieve + the requested frequency. If the request for the target frequency could not be + satisfied by platform firmware, then it usually means that power budget + conditions are in place, and "power capping" is taking place. + + 1.1 PCC interface: + ------------------ + The complete PCC specification is available here: + https://acpica.org/sites/acpica/files/Processor-Clocking-Control-v1p0.pdf + + PCC relies on a shared memory region that provides a channel for communication + between the OS and platform firmware. PCC also implements a "doorbell" that + is used by the OS to inform the platform firmware that a command has been + sent. + + The ACPI PCCH() method is used to discover the location of the PCC shared + memory region. The shared memory region header contains the "command" and + "status" interface. PCCH() also contains details on how to access the platform + doorbell. + + The following commands are supported by the PCC interface: + * Get Average Frequency + * Set Desired Frequency + + The ACPI PCCP() method is implemented for each logical processor and is + used to discover the offsets for the input and output buffers in the shared + memory region. + + When PCC mode is enabled, the platform will not expose processor performance + or throttle states (_PSS, _TSS and related ACPI objects) to OSPM. Therefore, + the native P-state driver (such as acpi-cpufreq for Intel, powernow-k8 for + AMD) will not load. + + However, OSPM remains in control of policy. The governor (eg: "ondemand") + computes the required performance for each processor based on server workload. + The PCC driver fills in the command interface, and the input buffer and + communicates the request to the platform firmware. The platform firmware is + responsible for delivering the requested performance. + + Each PCC command is "global" in scope and can affect all the logical CPUs in + the system. Therefore, PCC is capable of performing "group" updates. With PCC + the OS is capable of getting/setting the frequency of all the logical CPUs in + the system with a single call to the BIOS. + + 1.1.1 Get Average Frequency: + ---------------------------- + This command is used by the OSPM to query the running frequency of the + processor since the last time this command was completed. The output buffer + indicates the average unhalted frequency of the logical processor expressed as + a percentage of the nominal (ie: maximum) CPU frequency. The output buffer + also signifies if the CPU frequency is limited by a power budget condition. + + 1.1.2 Set Desired Frequency: + ---------------------------- + This command is used by the OSPM to communicate to the platform firmware the + desired frequency for a logical processor. The output buffer is currently + ignored by OSPM. The next invocation of "Get Average Frequency" will inform + OSPM if the desired frequency was achieved or not. + + 1.2 Platforms affected: + ----------------------- + The PCC driver will load on any system where the platform firmware: + * supports the PCC interface, and the associated PCCH() and PCCP() methods + * assumes responsibility for managing the hardware clocking controls in order + to deliver the requested processor performance + + Currently, certain HP ProLiant platforms implement the PCC interface. On those + platforms PCC is the "default" choice. + + However, it is possible to disable this interface via a BIOS setting. In + such an instance, as is also the case on platforms where the PCC interface + is not implemented, the PCC driver will fail to load silently. + + 2. Driver and /sys details: + --------------------------- + When the driver loads, it merely prints the lowest and the highest CPU + frequencies supported by the platform firmware. + + The PCC driver loads with a message such as: + pcc-cpufreq: (v1.00.00) driver loaded with frequency limits: 1600 MHz, 2933 + MHz + + This means that the OPSM can request the CPU to run at any frequency in + between the limits (1600 MHz, and 2933 MHz) specified in the message. + + Internally, there is no need for the driver to convert the "target" frequency + to a corresponding P-state. + + The VERSION number for the driver will be of the format v.xy.ab. + eg: 1.00.02 + ----- -- + | | + | -- this will increase with bug fixes/enhancements to the driver + |-- this is the version of the PCC specification the driver adheres to + + + The following is a brief discussion on some of the fields exported via the + /sys filesystem and how their values are affected by the PCC driver: + + 2.1 scaling_available_frequencies: + ---------------------------------- + scaling_available_frequencies is not created in /sys. No intermediate + frequencies need to be listed because the BIOS will try to achieve any + frequency, within limits, requested by the governor. A frequency does not have + to be strictly associated with a P-state. + + 2.2 cpuinfo_transition_latency: + ------------------------------- + The cpuinfo_transition_latency field is 0. The PCC specification does + not include a field to expose this value currently. + + 2.3 cpuinfo_cur_freq: + --------------------- + A) Often cpuinfo_cur_freq will show a value different than what is declared + in the scaling_available_frequencies or scaling_cur_freq, or scaling_max_freq. + This is due to "turbo boost" available on recent Intel processors. If certain + conditions are met the BIOS can achieve a slightly higher speed than requested + by OSPM. An example: + + scaling_cur_freq : 2933000 + cpuinfo_cur_freq : 3196000 + + B) There is a round-off error associated with the cpuinfo_cur_freq value. + Since the driver obtains the current frequency as a "percentage" (%) of the + nominal frequency from the BIOS, sometimes, the values displayed by + scaling_cur_freq and cpuinfo_cur_freq may not match. An example: + + scaling_cur_freq : 1600000 + cpuinfo_cur_freq : 1583000 + + In this example, the nominal frequency is 2933 MHz. The driver obtains the + current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency: + + 54% of 2933 MHz = 1583 MHz + + Nominal frequency is the maximum frequency of the processor, and it usually + corresponds to the frequency of the P0 P-state. + + 2.4 related_cpus: + ----------------- + The related_cpus field is identical to affected_cpus. + + affected_cpus : 4 + related_cpus : 4 + + Currently, the PCC driver does not evaluate _PSD. The platforms that support + PCC do not implement SW_ALL. So OSPM doesn't need to perform any coordination + to ensure that the same frequency is requested of all dependent CPUs. + + 3. Caveats: + ----------- + The "cpufreq_stats" module in its present form cannot be loaded and + expected to work with the PCC driver. Since the "cpufreq_stats" module + provides information wrt each P-state, it is not applicable to the PCC driver. diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index 6a06dc473dd6..5605cc6f9560 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -583,20 +583,17 @@ Power Management Quality of Service for CPUs The power management quality of service (PM QoS) framework in the Linux kernel allows kernel code and user space processes to set constraints on various energy-efficiency features of the kernel to prevent performance from dropping -below a required level. The PM QoS constraints can be set globally, in -predefined categories referred to as PM QoS classes, or against individual -devices. +below a required level. CPU idle time management can be affected by PM QoS in two ways, through the -global constraint in the ``PM_QOS_CPU_DMA_LATENCY`` class and through the -resume latency constraints for individual CPUs. Kernel code (e.g. device -drivers) can set both of them with the help of special internal interfaces -provided by the PM QoS framework. User space can modify the former by opening -the :file:`cpu_dma_latency` special device file under :file:`/dev/` and writing -a binary value (interpreted as a signed 32-bit integer) to it. In turn, the -resume latency constraint for a CPU can be modified by user space by writing a -string (representing a signed 32-bit integer) to the -:file:`power/pm_qos_resume_latency_us` file under +global CPU latency limit and through the resume latency constraints for +individual CPUs. Kernel code (e.g. device drivers) can set both of them with +the help of special internal interfaces provided by the PM QoS framework. User +space can modify the former by opening the :file:`cpu_dma_latency` special +device file under :file:`/dev/` and writing a binary value (interpreted as a +signed 32-bit integer) to it. In turn, the resume latency constraint for a CPU +can be modified from user space by writing a string (representing a signed +32-bit integer) to the :file:`power/pm_qos_resume_latency_us` file under :file:`/sys/devices/system/cpu/cpu<N>/` in ``sysfs``, where the CPU number ``<N>`` is allocated at the system initialization time. Negative values will be rejected in both cases and, also in both cases, the written integer @@ -605,32 +602,34 @@ number will be interpreted as a requested PM QoS constraint in microseconds. The requested value is not automatically applied as a new constraint, however, as it may be less restrictive (greater in this particular case) than another constraint previously requested by someone else. For this reason, the PM QoS -framework maintains a list of requests that have been made so far in each -global class and for each device, aggregates them and applies the effective -(minimum in this particular case) value as the new constraint. +framework maintains a list of requests that have been made so far for the +global CPU latency limit and for each individual CPU, aggregates them and +applies the effective (minimum in this particular case) value as the new +constraint. In fact, opening the :file:`cpu_dma_latency` special device file causes a new -PM QoS request to be created and added to the priority list of requests in the -``PM_QOS_CPU_DMA_LATENCY`` class and the file descriptor coming from the -"open" operation represents that request. If that file descriptor is then -used for writing, the number written to it will be associated with the PM QoS -request represented by it as a new requested constraint value. Next, the -priority list mechanism will be used to determine the new effective value of -the entire list of requests and that effective value will be set as a new -constraint. Thus setting a new requested constraint value will only change the -real constraint if the effective "list" value is affected by it. In particular, -for the ``PM_QOS_CPU_DMA_LATENCY`` class it only affects the real constraint if -it is the minimum of the requested constraints in the list. The process holding -a file descriptor obtained by opening the :file:`cpu_dma_latency` special device -file controls the PM QoS request associated with that file descriptor, but it -controls this particular PM QoS request only. +PM QoS request to be created and added to a global priority list of CPU latency +limit requests and the file descriptor coming from the "open" operation +represents that request. If that file descriptor is then used for writing, the +number written to it will be associated with the PM QoS request represented by +it as a new requested limit value. Next, the priority list mechanism will be +used to determine the new effective value of the entire list of requests and +that effective value will be set as a new CPU latency limit. Thus requesting a +new limit value will only change the real limit if the effective "list" value is +affected by it, which is the case if it is the minimum of the requested values +in the list. + +The process holding a file descriptor obtained by opening the +:file:`cpu_dma_latency` special device file controls the PM QoS request +associated with that file descriptor, but it controls this particular PM QoS +request only. Closing the :file:`cpu_dma_latency` special device file or, more precisely, the file descriptor obtained while opening it, causes the PM QoS request associated -with that file descriptor to be removed from the ``PM_QOS_CPU_DMA_LATENCY`` -class priority list and destroyed. If that happens, the priority list mechanism -will be used, again, to determine the new effective value for the whole list -and that value will become the new real constraint. +with that file descriptor to be removed from the global priority list of CPU +latency limit requests and destroyed. If that happens, the priority list +mechanism will be used again, to determine the new effective value for the whole +list and that value will become the new limit. In turn, for each CPU there is one resume latency PM QoS request associated with the :file:`power/pm_qos_resume_latency_us` file under @@ -647,10 +646,10 @@ CPU in question every time the list of requests is updated this way or another (there may be other requests coming from kernel code in that list). CPU idle time governors are expected to regard the minimum of the global -effective ``PM_QOS_CPU_DMA_LATENCY`` class constraint and the effective -resume latency constraint for the given CPU as the upper limit for the exit -latency of the idle states they can select for that CPU. They should never -select any idle states with exit latency beyond that limit. +(effective) CPU latency limit and the effective resume latency constraint for +the given CPU as the upper limit for the exit latency of the idle states that +they are allowed to select for that CPU. They should never select any idle +states with exit latency beyond that limit. Idle States Control Via Kernel Command Line diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index 67e414e34f37..ad392f3aee06 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -734,10 +734,10 @@ References ========== .. [1] Kristen Accardi, *Balancing Power and Performance in the Linux Kernel*, - http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf + https://events.static.linuxfound.org/sites/events/files/slides/LinuxConEurope_2015.pdf .. [2] *Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3: System Programming Guide*, - http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html + https://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html .. [3] *Advanced Configuration and Power Interface Specification*, https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst index 88f717e59a42..0a38cdf39df1 100644 --- a/Documentation/admin-guide/pm/working-state.rst +++ b/Documentation/admin-guide/pm/working-state.rst @@ -11,4 +11,5 @@ Working-State Power Management intel_idle cpufreq intel_pstate + cpufreq_drivers intel_epb diff --git a/Documentation/cpu-freq/amd-powernow.txt b/Documentation/cpu-freq/amd-powernow.txt deleted file mode 100644 index 254da155fa47..000000000000 --- a/Documentation/cpu-freq/amd-powernow.txt +++ /dev/null @@ -1,38 +0,0 @@ - -PowerNow! and Cool'n'Quiet are AMD names for frequency -management capabilities in AMD processors. As the hardware -implementation changes in new generations of the processors, -there is a different cpu-freq driver for each generation. - -Note that the driver's will not load on the "wrong" hardware, -so it is safe to try each driver in turn when in doubt as to -which is the correct driver. - -Note that the functionality to change frequency (and voltage) -is not available in all processors. The drivers will refuse -to load on processors without this capability. The capability -is detected with the cpuid instruction. - -The drivers use BIOS supplied tables to obtain frequency and -voltage information appropriate for a particular platform. -Frequency transitions will be unavailable if the BIOS does -not supply these tables. - -6th Generation: powernow-k6 - -7th Generation: powernow-k7: Athlon, Duron, Geode. - -8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron. -Documentation on this functionality in 8th generation processors -is available in the "BIOS and Kernel Developer's Guide", publication -26094, in chapter 9, available for download from www.amd.com. - -BIOS supplied data, for powernow-k7 and for powernow-k8, may be -from either the PSB table or from ACPI objects. The ACPI support -is only available if the kernel config sets CONFIG_ACPI_PROCESSOR. -The powernow-k8 driver will attempt to use ACPI if so configured, -and fall back to PST if that fails. -The powernow-k7 driver will try to use the PSB support first, and -fall back to ACPI if the PSB support fails. A module parameter, -acpi_force, is provided to force ACPI support to be used instead -of PSB support. diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.rst index ed577d9c154b..33cb90bd1d8f 100644 --- a/Documentation/cpu-freq/core.txt +++ b/Documentation/cpu-freq/core.rst @@ -1,31 +1,23 @@ - CPU frequency and voltage scaling code in the Linux(TM) kernel +.. SPDX-License-Identifier: GPL-2.0 +============================================================= +General description of the CPUFreq core and CPUFreq notifiers +============================================================= - L i n u x C P U F r e q +Authors: + - Dominik Brodowski <linux@brodo.de> + - David Kimdon <dwhedon@debian.org> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> - C P U F r e q C o r e +.. Contents: - - Dominik Brodowski <linux@brodo.de> - David Kimdon <dwhedon@debian.org> - 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. CPUFreq core and interfaces -2. CPUFreq notifiers -3. CPUFreq Table Generation with Operating Performance Point (OPP) + 1. CPUFreq core and interfaces + 2. CPUFreq notifiers + 3. CPUFreq Table Generation with Operating Performance Point (OPP) 1. General Information -======================= +====================== The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This cpufreq code offers a standardized interface for the CPUFreq @@ -63,7 +55,7 @@ The phase is specified in the second argument to the notifier. The phase is CPUFREQ_CREATE_POLICY when the policy is first created and it is CPUFREQ_REMOVE_POLICY when the policy is removed. -The third argument, a void *pointer, points to a struct cpufreq_policy +The third argument, a ``void *pointer``, points to a struct cpufreq_policy consisting of several values, including min, max (the lower and upper frequencies (in kHz) of the new policy). @@ -80,10 +72,13 @@ CPUFREQ_POSTCHANGE. The third argument is a struct cpufreq_freqs with the following values: -cpu - number of the affected CPU -old - old frequency -new - new frequency -flags - flags of the cpufreq driver + +===== =========================== +cpu number of the affected CPU +old old frequency +new new frequency +flags flags of the cpufreq driver +===== =========================== 3. CPUFreq Table Generation with Operating Performance Point (OPP) ================================================================== @@ -94,9 +89,12 @@ dev_pm_opp_init_cpufreq_table - the OPP layer's internal information about the available frequencies into a format readily providable to cpufreq. - WARNING: Do not use this function in interrupt context. + .. Warning:: + + Do not use this function in interrupt context. + + Example:: - Example: soc_pm_init() { /* Do things */ @@ -106,7 +104,10 @@ dev_pm_opp_init_cpufreq_table - /* Do other things */ } - NOTE: This function is available only if CONFIG_CPU_FREQ is enabled in - addition to CONFIG_PM_OPP. + .. note:: + + This function is available only if CONFIG_CPU_FREQ is enabled in + addition to CONFIG_PM_OPP. -dev_pm_opp_free_cpufreq_table - Free up the table allocated by dev_pm_opp_init_cpufreq_table +dev_pm_opp_free_cpufreq_table + Free up the table allocated by dev_pm_opp_init_cpufreq_table diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.rst index 6e353d00cdc6..a697278ce190 100644 --- a/Documentation/cpu-freq/cpu-drivers.txt +++ b/Documentation/cpu-freq/cpu-drivers.rst @@ -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 @@ -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. @@ -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 @@ -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 @@ -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. @@ -175,8 +172,8 @@ 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. @@ -184,9 +181,9 @@ 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 @@ -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 @@ -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; diff --git a/Documentation/cpu-freq/cpufreq-nforce2.txt b/Documentation/cpu-freq/cpufreq-nforce2.txt deleted file mode 100644 index babce1315026..000000000000 --- a/Documentation/cpu-freq/cpufreq-nforce2.txt +++ /dev/null @@ -1,19 +0,0 @@ - -The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms. - -This works better than on other platforms, because the FSB of the CPU -can be controlled independently from the PCI/AGP clock. - -The module has two options: - - fid: multiplier * 10 (for example 8.5 = 85) - min_fsb: minimum FSB - -If not set, fid is calculated from the current CPU speed and the FSB. -min_fsb defaults to FSB at boot time - 50 MHz. - -IMPORTANT: The available range is limited downwards! - Also the minimum available FSB can differ, for systems - booting with 200 MHz, 150 should always work. - - diff --git a/Documentation/cpu-freq/cpufreq-stats.txt b/Documentation/cpu-freq/cpufreq-stats.rst index 14378cecb172..9ad695b1c7db 100644 --- a/Documentation/cpu-freq/cpufreq-stats.txt +++ b/Documentation/cpu-freq/cpufreq-stats.rst @@ -1,21 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0 - CPU frequency and voltage scaling statistics in the Linux(TM) kernel +========================================== +General Description of sysfs CPUFreq Stats +========================================== +information for users - L i n u x c p u f r e q - s t a t s d r i v e r - - information for users - +Author: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> +.. Contents - Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> - -Contents -1. Introduction -2. Statistics Provided (with example) -3. Configuring cpufreq-stats + 1. Introduction + 2. Statistics Provided (with example) + 3. Configuring cpufreq-stats 1. Introduction +=============== cpufreq-stats is a driver that provides CPU frequency statistics for each CPU. These statistics are provided in /sysfs as a bunch of read_only interfaces. This @@ -28,8 +30,10 @@ that may be running on your CPU. So, it will work with any cpufreq_driver. 2. Statistics Provided (with example) +===================================== cpufreq stats provides following statistics (explained in detail below). + - time_in_state - total_trans - trans_table @@ -39,53 +43,57 @@ All the statistics will be from the time the stats driver has been inserted statistic is done. Obviously, stats driver will not have any information about the frequency transitions before the stats driver insertion. --------------------------------------------------------------------------------- -<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l -total 0 -drwxr-xr-x 2 root root 0 May 14 16:06 . -drwxr-xr-x 3 root root 0 May 14 15:58 .. ---w------- 1 root root 4096 May 14 16:06 reset --r--r--r-- 1 root root 4096 May 14 16:06 time_in_state --r--r--r-- 1 root root 4096 May 14 16:06 total_trans --r--r--r-- 1 root root 4096 May 14 16:06 trans_table --------------------------------------------------------------------------------- - -- reset +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l + total 0 + drwxr-xr-x 2 root root 0 May 14 16:06 . + drwxr-xr-x 3 root root 0 May 14 15:58 .. + --w------- 1 root root 4096 May 14 16:06 reset + -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state + -r--r--r-- 1 root root 4096 May 14 16:06 total_trans + -r--r--r-- 1 root root 4096 May 14 16:06 trans_table + +- **reset** + Write-only attribute that can be used to reset the stat counters. This can be useful for evaluating system behaviour under different governors without the need for a reboot. -- time_in_state +- **time_in_state** + This gives the amount of time spent in each of the frequencies supported by this CPU. The cat output will have "<frequency> <time>" pair in each line, which will mean this CPU spent <time> usertime units of time at <frequency>. Output -will have one line for each of the supported frequencies. usertime units here +will have one line for each of the supported frequencies. usertime units here is 10mS (similar to other time exported in /proc). --------------------------------------------------------------------------------- -<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state -3600000 2089 -3400000 136 -3200000 34 -3000000 67 -2800000 172488 --------------------------------------------------------------------------------- +:: + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state + 3600000 2089 + 3400000 136 + 3200000 34 + 3000000 67 + 2800000 172488 -- total_trans -This gives the total number of frequency transitions on this CPU. The cat + +- **total_trans** + +This gives the total number of frequency transitions on this CPU. The cat output will have a single count which is the total number of frequency transitions. --------------------------------------------------------------------------------- -<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans -20 --------------------------------------------------------------------------------- +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans + 20 + +- **trans_table** -- trans_table This will give a fine grained information about all the CPU frequency transitions. The cat output here is a two dimensional matrix, where an entry -<i,j> (row i, column j) represents the count of number of transitions from +<i,j> (row i, column j) represents the count of number of transitions from Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in which the driver has provided the frequency table initially to the cpufreq core and so can be sorted (ascending or descending) or unsorted. The output here @@ -95,26 +103,27 @@ readability. If the transition table is bigger than PAGE_SIZE, reading this will return an -EFBIG error. --------------------------------------------------------------------------------- -<mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table - From : To - : 3600000 3400000 3200000 3000000 2800000 - 3600000: 0 5 0 0 0 - 3400000: 4 0 2 0 0 - 3200000: 0 1 0 2 0 - 3000000: 0 0 1 0 3 - 2800000: 0 0 0 2 0 --------------------------------------------------------------------------------- +:: + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table + From : To + : 3600000 3400000 3200000 3000000 2800000 + 3600000: 0 5 0 0 0 + 3400000: 4 0 2 0 0 + 3200000: 0 1 0 2 0 + 3000000: 0 0 1 0 3 + 2800000: 0 0 0 2 0 3. Configuring cpufreq-stats +============================ + +To configure cpufreq-stats in your kernel:: -To configure cpufreq-stats in your kernel -Config Main Menu - Power management options (ACPI, APM) ---> - CPU Frequency scaling ---> - [*] CPU Frequency scaling - [*] CPU frequency translation statistics + Config Main Menu + Power management options (ACPI, APM) ---> + CPU Frequency scaling ---> + [*] CPU Frequency scaling + [*] CPU frequency translation statistics "CPU Frequency scaling" (CONFIG_CPU_FREQ) should be enabled to configure diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst new file mode 100644 index 000000000000..aba7831ab1cb --- /dev/null +++ b/Documentation/cpu-freq/index.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================================== +Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel +============================================================================== + +Author: Dominik Brodowski <linux@brodo.de> + + 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. + + +.. toctree:: + :maxdepth: 1 + + core + cpu-drivers + cpufreq-stats + +Mailing List +------------ +There is a CPU frequency changing CVS commit and general list where +you can report bugs, problems or submit patches. To post a message, +send an email to linux-pm@vger.kernel.org. + +Links +----- +the FTP archives: +* ftp://ftp.linux.org.uk/pub/linux/cpufreq/ + +how to access the CVS repository: +* http://cvs.arm.linux.org.uk/ + +the CPUFreq Mailing list: +* http://vger.kernel.org/vger-lists.html#linux-pm + +Clock and voltage scaling for the SA-1100: +* http://www.lartmaker.nl/projects/scaling diff --git a/Documentation/cpu-freq/index.txt b/Documentation/cpu-freq/index.txt deleted file mode 100644 index c15e75386a05..000000000000 --- a/Documentation/cpu-freq/index.txt +++ /dev/null @@ -1,56 +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 - - - - - Dominik Brodowski <linux@brodo.de> - - - - 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. - - - -Documents in this directory: ----------------------------- - -amd-powernow.txt - AMD powernow driver specific file. - -core.txt - General description of the CPUFreq core and - of CPUFreq notifiers. - -cpu-drivers.txt - How to implement a new cpufreq processor driver. - -cpufreq-nforce2.txt - nVidia nForce2 platform specific file. - -cpufreq-stats.txt - General description of sysfs cpufreq stats. - -index.txt - File index, Mailing list and Links (this document) - -pcc-cpufreq.txt - PCC cpufreq driver specific file. - - -Mailing List ------------- -There is a CPU frequency changing CVS commit and general list where -you can report bugs, problems or submit patches. To post a message, -send an email to linux-pm@vger.kernel.org. - -Links ------ -the FTP archives: -* ftp://ftp.linux.org.uk/pub/linux/cpufreq/ - -how to access the CVS repository: -* http://cvs.arm.linux.org.uk/ - -the CPUFreq Mailing list: -* http://vger.kernel.org/vger-lists.html#linux-pm - -Clock and voltage scaling for the SA-1100: -* http://www.lartmaker.nl/projects/scaling diff --git a/Documentation/cpu-freq/pcc-cpufreq.txt b/Documentation/cpu-freq/pcc-cpufreq.txt deleted file mode 100644 index 9e3c3b33514c..000000000000 --- a/Documentation/cpu-freq/pcc-cpufreq.txt +++ /dev/null @@ -1,207 +0,0 @@ -/* - * pcc-cpufreq.txt - PCC interface documentation - * - * Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com> - * Copyright (C) 2009 Hewlett-Packard Development Company, L.P. - * Nagananda Chumbalkar <nagananda.chumbalkar@hp.com> - * - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; version 2 of the License. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or NON - * INFRINGEMENT. See the GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License along - * with this program; if not, write to the Free Software Foundation, Inc., - * 675 Mass Ave, Cambridge, MA 02139, USA. - * - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - - - Processor Clocking Control Driver - --------------------------------- - -Contents: ---------- -1. Introduction -1.1 PCC interface -1.1.1 Get Average Frequency -1.1.2 Set Desired Frequency -1.2 Platforms affected -2. Driver and /sys details -2.1 scaling_available_frequencies -2.2 cpuinfo_transition_latency -2.3 cpuinfo_cur_freq -2.4 related_cpus -3. Caveats - -1. Introduction: ----------------- -Processor Clocking Control (PCC) is an interface between the platform -firmware and OSPM. It is a mechanism for coordinating processor -performance (ie: frequency) between the platform firmware and the OS. - -The PCC driver (pcc-cpufreq) allows OSPM to take advantage of the PCC -interface. - -OS utilizes the PCC interface to inform platform firmware what frequency the -OS wants for a logical processor. The platform firmware attempts to achieve -the requested frequency. If the request for the target frequency could not be -satisfied by platform firmware, then it usually means that power budget -conditions are in place, and "power capping" is taking place. - -1.1 PCC interface: ------------------- -The complete PCC specification is available here: -http://www.acpica.org/download/Processor-Clocking-Control-v1p0.pdf - -PCC relies on a shared memory region that provides a channel for communication -between the OS and platform firmware. PCC also implements a "doorbell" that -is used by the OS to inform the platform firmware that a command has been -sent. - -The ACPI PCCH() method is used to discover the location of the PCC shared -memory region. The shared memory region header contains the "command" and -"status" interface. PCCH() also contains details on how to access the platform -doorbell. - -The following commands are supported by the PCC interface: -* Get Average Frequency -* Set Desired Frequency - -The ACPI PCCP() method is implemented for each logical processor and is -used to discover the offsets for the input and output buffers in the shared -memory region. - -When PCC mode is enabled, the platform will not expose processor performance -or throttle states (_PSS, _TSS and related ACPI objects) to OSPM. Therefore, -the native P-state driver (such as acpi-cpufreq for Intel, powernow-k8 for -AMD) will not load. - -However, OSPM remains in control of policy. The governor (eg: "ondemand") -computes the required performance for each processor based on server workload. -The PCC driver fills in the command interface, and the input buffer and -communicates the request to the platform firmware. The platform firmware is -responsible for delivering the requested performance. - -Each PCC command is "global" in scope and can affect all the logical CPUs in -the system. Therefore, PCC is capable of performing "group" updates. With PCC -the OS is capable of getting/setting the frequency of all the logical CPUs in -the system with a single call to the BIOS. - -1.1.1 Get Average Frequency: ----------------------------- -This command is used by the OSPM to query the running frequency of the -processor since the last time this command was completed. The output buffer -indicates the average unhalted frequency of the logical processor expressed as -a percentage of the nominal (ie: maximum) CPU frequency. The output buffer -also signifies if the CPU frequency is limited by a power budget condition. - -1.1.2 Set Desired Frequency: ----------------------------- -This command is used by the OSPM to communicate to the platform firmware the -desired frequency for a logical processor. The output buffer is currently -ignored by OSPM. The next invocation of "Get Average Frequency" will inform -OSPM if the desired frequency was achieved or not. - -1.2 Platforms affected: ------------------------ -The PCC driver will load on any system where the platform firmware: -* supports the PCC interface, and the associated PCCH() and PCCP() methods -* assumes responsibility for managing the hardware clocking controls in order -to deliver the requested processor performance - -Currently, certain HP ProLiant platforms implement the PCC interface. On those -platforms PCC is the "default" choice. - -However, it is possible to disable this interface via a BIOS setting. In -such an instance, as is also the case on platforms where the PCC interface -is not implemented, the PCC driver will fail to load silently. - -2. Driver and /sys details: ---------------------------- -When the driver loads, it merely prints the lowest and the highest CPU -frequencies supported by the platform firmware. - -The PCC driver loads with a message such as: -pcc-cpufreq: (v1.00.00) driver loaded with frequency limits: 1600 MHz, 2933 -MHz - -This means that the OPSM can request the CPU to run at any frequency in -between the limits (1600 MHz, and 2933 MHz) specified in the message. - -Internally, there is no need for the driver to convert the "target" frequency -to a corresponding P-state. - -The VERSION number for the driver will be of the format v.xy.ab. -eg: 1.00.02 - ----- -- - | | - | -- this will increase with bug fixes/enhancements to the driver - |-- this is the version of the PCC specification the driver adheres to - - -The following is a brief discussion on some of the fields exported via the -/sys filesystem and how their values are affected by the PCC driver: - -2.1 scaling_available_frequencies: ----------------------------------- -scaling_available_frequencies is not created in /sys. No intermediate -frequencies need to be listed because the BIOS will try to achieve any -frequency, within limits, requested by the governor. A frequency does not have -to be strictly associated with a P-state. - -2.2 cpuinfo_transition_latency: -------------------------------- -The cpuinfo_transition_latency field is 0. The PCC specification does -not include a field to expose this value currently. - -2.3 cpuinfo_cur_freq: ---------------------- -A) Often cpuinfo_cur_freq will show a value different than what is declared -in the scaling_available_frequencies or scaling_cur_freq, or scaling_max_freq. -This is due to "turbo boost" available on recent Intel processors. If certain -conditions are met the BIOS can achieve a slightly higher speed than requested -by OSPM. An example: - -scaling_cur_freq : 2933000 -cpuinfo_cur_freq : 3196000 - -B) There is a round-off error associated with the cpuinfo_cur_freq value. -Since the driver obtains the current frequency as a "percentage" (%) of the -nominal frequency from the BIOS, sometimes, the values displayed by -scaling_cur_freq and cpuinfo_cur_freq may not match. An example: - -scaling_cur_freq : 1600000 -cpuinfo_cur_freq : 1583000 - -In this example, the nominal frequency is 2933 MHz. The driver obtains the -current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency: - - 54% of 2933 MHz = 1583 MHz - -Nominal frequency is the maximum frequency of the processor, and it usually -corresponds to the frequency of the P0 P-state. - -2.4 related_cpus: ------------------ -The related_cpus field is identical to affected_cpus. - -affected_cpus : 4 -related_cpus : 4 - -Currently, the PCC driver does not evaluate _PSD. The platforms that support -PCC do not implement SW_ALL. So OSPM doesn't need to perform any coordination -to ensure that the same frequency is requested of all dependent CPUs. - -3. Caveats: ------------ -The "cpufreq_stats" module in its present form cannot be loaded and -expected to work with the PCC driver. Since the "cpufreq_stats" module -provides information wrt each P-state, it is not applicable to the PCC driver. diff --git a/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt b/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt index 4751029b9b74..64f07417ecfb 100644 --- a/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt +++ b/Documentation/devicetree/bindings/opp/qcom-nvmem-cpufreq.txt @@ -19,7 +19,8 @@ In 'cpu' nodes: In 'operating-points-v2' table: - compatible: Should be - - 'operating-points-v2-kryo-cpu' for apq8096 and msm8996. + - 'operating-points-v2-kryo-cpu' for apq8096, msm8996, msm8974, + apq8064, ipq8064, msm8960 and ipq8074. Optional properties: -------------------- diff --git a/Documentation/index.rst b/Documentation/index.rst index 6fdad61ee443..9df95bab4de8 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -99,6 +99,7 @@ needed). accounting/index block/index cdrom/index + cpu-freq/index ide/index fb/index fpga/index diff --git a/Documentation/power/pm_qos_interface.rst b/Documentation/power/pm_qos_interface.rst index 0d62d506caf0..69b0fe3e2542 100644 --- a/Documentation/power/pm_qos_interface.rst +++ b/Documentation/power/pm_qos_interface.rst @@ -7,86 +7,78 @@ performance expectations by drivers, subsystems and user space applications on one of the parameters. Two different PM QoS frameworks are available: -1. PM QoS classes for cpu_dma_latency -2. The per-device PM QoS framework provides the API to manage the + * CPU latency QoS. + * The per-device PM QoS framework provides the API to manage the per-device latency constraints and PM QoS flags. -Each parameters have defined units: - - * latency: usec - * timeout: usec - * throughput: kbs (kilo bit / sec) - * memory bandwidth: mbs (mega bit / sec) +The latency unit used in the PM QoS framework is the microsecond (usec). 1. PM QoS framework =================== -The infrastructure exposes multiple misc device nodes one per implemented -parameter. The set of parameters implement is defined by pm_qos_power_init() -and pm_qos_params.h. This is done because having the available parameters -being runtime configurable or changeable from a driver was seen as too easy to -abuse. - -For each parameter a list of performance requests is maintained along with -an aggregated target value. The aggregated target value is updated with -changes to the request list or elements of the list. Typically the -aggregated target value is simply the max or min of the request values held -in the parameter list elements. +A global list of CPU latency QoS requests is maintained along with an aggregated +(effective) target value. The aggregated target value is updated with changes +to the request list or elements of the list. For CPU latency QoS, the +aggregated target value is simply the min of the request values held in the list +elements. + Note: the aggregated target value is implemented as an atomic variable so that reading the aggregated value does not require any locking mechanism. +From kernel space the use of this interface is simple: -From kernel mode the use of this interface is simple: - -void pm_qos_add_request(handle, param_class, target_value): - Will insert an element into the list for that identified PM QoS class with the - target value. Upon change to this list the new target is recomputed and any - registered notifiers are called only if the target value is now different. - Clients of pm_qos need to save the returned handle for future use in other - pm_qos API functions. +void cpu_latency_qos_add_request(handle, target_value): + Will insert an element into the CPU latency QoS list with the target value. + Upon change to this list the new target is recomputed and any registered + notifiers are called only if the target value is now different. + Clients of PM QoS need to save the returned handle for future use in other + PM QoS API functions. -void pm_qos_update_request(handle, new_target_value): +void cpu_latency_qos_update_request(handle, new_target_value): Will update the list element pointed to by the handle with the new target value and recompute the new aggregated target, calling the notification tree if the target is changed. -void pm_qos_remove_request(handle): +void cpu_latency_qos_remove_request(handle): Will remove the element. After removal it will update the aggregate target and call the notification tree if the target was changed as a result of removing the request. -int pm_qos_request(param_class): - Returns the aggregated value for a given PM QoS class. +int cpu_latency_qos_limit(): + Returns the aggregated value for the CPU latency QoS. + +int cpu_latency_qos_request_active(handle): + Returns if the request is still active, i.e. it has not been removed from the + CPU latency QoS list. -int pm_qos_request_active(handle): - Returns if the request is still active, i.e. it has not been removed from a - PM QoS class constraints list. +int cpu_latency_qos_add_notifier(notifier): + Adds a notification callback function to the CPU latency QoS. The callback is + called when the aggregated value for the CPU latency QoS is changed. -int pm_qos_add_notifier(param_class, notifier): - Adds a notification callback function to the PM QoS class. The callback is - called when the aggregated value for the PM QoS class is changed. +int cpu_latency_qos_remove_notifier(notifier): + Removes the notification callback function from the CPU latency QoS. -int pm_qos_remove_notifier(int param_class, notifier): - Removes the notification callback function for the PM QoS class. +From user space: -From user mode: +The infrastructure exposes one device node, /dev/cpu_dma_latency, for the CPU +latency QoS. -Only processes can register a pm_qos request. To provide for automatic +Only processes can register a PM QoS request. To provide for automatic cleanup of a process, the interface requires the process to register its -parameter requests in the following way: +parameter requests as follows. -To register the default pm_qos target for the specific parameter, the process -must open /dev/cpu_dma_latency +To register the default PM QoS target for the CPU latency QoS, the process must +open /dev/cpu_dma_latency. As long as the device node is held open that process has a registered request on the parameter. -To change the requested target value the process needs to write an s32 value to -the open device node. Alternatively the user mode program could write a hex -string for the value using 10 char long format e.g. "0x12345678". This -translates to a pm_qos_update_request call. +To change the requested target value, the process needs to write an s32 value to +the open device node. Alternatively, it can write a hex string for the value +using the 10 char long format e.g. "0x12345678". This translates to a +cpu_latency_qos_update_request() call. To remove the user mode request for a target value simply close the device node. diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index ab8406c84254..0553008b6279 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -382,6 +382,12 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: nonzero, increment the counter and return 1; otherwise return 0 without changing the counter + `int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);` + - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the + runtime PM status is RPM_ACTIVE, and either ign_usage_count is true + or the device's usage_count is non-zero, increment the counter and + return 1; otherwise return 0 without changing the counter + `void pm_runtime_put_noidle(struct device *dev);` - decrement the device's usage counter diff --git a/Documentation/power/userland-swsusp.rst b/Documentation/power/userland-swsusp.rst index a0fa51bb1a4d..1cf62d80a9ca 100644 --- a/Documentation/power/userland-swsusp.rst +++ b/Documentation/power/userland-swsusp.rst @@ -69,11 +69,13 @@ SNAPSHOT_PREF_IMAGE_SIZE SNAPSHOT_GET_IMAGE_SIZE return the actual size of the hibernation image + (the last argument should be a pointer to a loff_t variable that + will contain the result if the call is successful) SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the - last argument should be a pointer to an unsigned int variable that will - contain the result if the call is successful). + return the amount of available swap in bytes + (the last argument should be a pointer to a loff_t variable that + will contain the result if the call is successful) SNAPSHOT_ALLOC_SWAP_PAGE allocate a swap page from the resume partition diff --git a/Documentation/trace/events-power.rst b/Documentation/trace/events-power.rst index 2ef318962e29..f45bf11fa88d 100644 --- a/Documentation/trace/events-power.rst +++ b/Documentation/trace/events-power.rst @@ -75,16 +75,6 @@ The PM QoS events are used for QoS add/update/remove request and for target/flags update. :: - pm_qos_add_request "pm_qos_class=%s value=%d" - pm_qos_update_request "pm_qos_class=%s value=%d" - pm_qos_remove_request "pm_qos_class=%s value=%d" - pm_qos_update_request_timeout "pm_qos_class=%s value=%d, timeout_us=%ld" - -The first parameter gives the QoS class name (e.g. "CPU_DMA_LATENCY"). -The second parameter is value to be added/updated/removed. -The third parameter is timeout value in usec. -:: - pm_qos_update_target "action=%s prev_value=%d curr_value=%d" pm_qos_update_flags "action=%s prev_value=0x%x curr_value=0x%x" @@ -92,7 +82,7 @@ The first parameter gives the QoS action name (e.g. "ADD_REQ"). The second parameter is the previous QoS value. The third parameter is the current QoS value to update. -And, there are also events used for device PM QoS add/update/remove request. +There are also events used for device PM QoS add/update/remove request. :: dev_pm_qos_add_request "device=%s type=%s new_value=%d" @@ -103,3 +93,12 @@ The first parameter gives the device name which tries to add/update/remove QoS requests. The second parameter gives the request type (e.g. "DEV_PM_QOS_RESUME_LATENCY"). The third parameter is value to be added/updated/removed. + +And, there are events used for CPU latency QoS add/update/remove request. +:: + + pm_qos_add_request "value=%d" + pm_qos_update_request "value=%d" + pm_qos_remove_request "value=%d" + +The parameter is the value to be added/updated/removed. |