0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======================================================
0004 Legacy Documentation of CPU Performance Scaling Drivers
0005 =======================================================
0006
0007 Included below are historic documents describing assorted
0008 :doc:`CPU performance scaling <cpufreq>` drivers. They are reproduced verbatim,
0009 with the original white space formatting and indentation preserved, except for
0010 the added leading space character in every line of text.
0011
0012
0013 AMD PowerNow! Drivers
0014 =====================
0015
0016 ::
0017
0018 PowerNow! and Cool'n'Quiet are AMD names for frequency
0019 management capabilities in AMD processors. As the hardware
0020 implementation changes in new generations of the processors,
0021 there is a different cpu-freq driver for each generation.
0022
0023 Note that the driver's will not load on the "wrong" hardware,
0024 so it is safe to try each driver in turn when in doubt as to
0025 which is the correct driver.
0026
0027 Note that the functionality to change frequency (and voltage)
0028 is not available in all processors. The drivers will refuse
0029 to load on processors without this capability. The capability
0030 is detected with the cpuid instruction.
0031
0032 The drivers use BIOS supplied tables to obtain frequency and
0033 voltage information appropriate for a particular platform.
0034 Frequency transitions will be unavailable if the BIOS does
0035 not supply these tables.
0036
0037 6th Generation: powernow-k6
0038
0039 7th Generation: powernow-k7: Athlon, Duron, Geode.
0040
0041 8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron.
0042 Documentation on this functionality in 8th generation processors
0043 is available in the "BIOS and Kernel Developer's Guide", publication
0044 26094, in chapter 9, available for download from www.amd.com.
0045
0046 BIOS supplied data, for powernow-k7 and for powernow-k8, may be
0047 from either the PSB table or from ACPI objects. The ACPI support
0048 is only available if the kernel config sets CONFIG_ACPI_PROCESSOR.
0049 The powernow-k8 driver will attempt to use ACPI if so configured,
0050 and fall back to PST if that fails.
0051 The powernow-k7 driver will try to use the PSB support first, and
0052 fall back to ACPI if the PSB support fails. A module parameter,
0053 acpi_force, is provided to force ACPI support to be used instead
0054 of PSB support.
0055
0056
0057 ``cpufreq-nforce2``
0058 ===================
0059
0060 ::
0061
0062 The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms.
0063
0064 This works better than on other platforms, because the FSB of the CPU
0065 can be controlled independently from the PCI/AGP clock.
0066
0067 The module has two options:
0068
0069 fid: multiplier * 10 (for example 8.5 = 85)
0070 min_fsb: minimum FSB
0071
0072 If not set, fid is calculated from the current CPU speed and the FSB.
0073 min_fsb defaults to FSB at boot time - 50 MHz.
0074
0075 IMPORTANT: The available range is limited downwards!
0076 Also the minimum available FSB can differ, for systems
0077 booting with 200 MHz, 150 should always work.
0078
0079
0080 ``pcc-cpufreq``
0081 ===============
0082
0083 ::
0084
0085 /*
0086 * pcc-cpufreq.txt - PCC interface documentation
0087 *
0088 * Copyright (C) 2009 Red Hat, Matthew Garrett <mjg@redhat.com>
0089 * Copyright (C) 2009 Hewlett-Packard Development Company, L.P.
0090 * Nagananda Chumbalkar <nagananda.chumbalkar@hp.com>
0091 */
0092
0093
0094 Processor Clocking Control Driver
0095 ---------------------------------
0096
0097 Contents:
0098 ---------
0099 1. Introduction
0100 1.1 PCC interface
0101 1.1.1 Get Average Frequency
0102 1.1.2 Set Desired Frequency
0103 1.2 Platforms affected
0104 2. Driver and /sys details
0105 2.1 scaling_available_frequencies
0106 2.2 cpuinfo_transition_latency
0107 2.3 cpuinfo_cur_freq
0108 2.4 related_cpus
0109 3. Caveats
0110
0111 1. Introduction:
0112 ----------------
0113 Processor Clocking Control (PCC) is an interface between the platform
0114 firmware and OSPM. It is a mechanism for coordinating processor
0115 performance (ie: frequency) between the platform firmware and the OS.
0116
0117 The PCC driver (pcc-cpufreq) allows OSPM to take advantage of the PCC
0118 interface.
0119
0120 OS utilizes the PCC interface to inform platform firmware what frequency the
0121 OS wants for a logical processor. The platform firmware attempts to achieve
0122 the requested frequency. If the request for the target frequency could not be
0123 satisfied by platform firmware, then it usually means that power budget
0124 conditions are in place, and "power capping" is taking place.
0125
0126 1.1 PCC interface:
0127 ------------------
0128 The complete PCC specification is available here:
0129 https://acpica.org/sites/acpica/files/Processor-Clocking-Control-v1p0.pdf
0130
0131 PCC relies on a shared memory region that provides a channel for communication
0132 between the OS and platform firmware. PCC also implements a "doorbell" that
0133 is used by the OS to inform the platform firmware that a command has been
0134 sent.
0135
0136 The ACPI PCCH() method is used to discover the location of the PCC shared
0137 memory region. The shared memory region header contains the "command" and
0138 "status" interface. PCCH() also contains details on how to access the platform
0139 doorbell.
0140
0141 The following commands are supported by the PCC interface:
0142 * Get Average Frequency
0143 * Set Desired Frequency
0144
0145 The ACPI PCCP() method is implemented for each logical processor and is
0146 used to discover the offsets for the input and output buffers in the shared
0147 memory region.
0148
0149 When PCC mode is enabled, the platform will not expose processor performance
0150 or throttle states (_PSS, _TSS and related ACPI objects) to OSPM. Therefore,
0151 the native P-state driver (such as acpi-cpufreq for Intel, powernow-k8 for
0152 AMD) will not load.
0153
0154 However, OSPM remains in control of policy. The governor (eg: "ondemand")
0155 computes the required performance for each processor based on server workload.
0156 The PCC driver fills in the command interface, and the input buffer and
0157 communicates the request to the platform firmware. The platform firmware is
0158 responsible for delivering the requested performance.
0159
0160 Each PCC command is "global" in scope and can affect all the logical CPUs in
0161 the system. Therefore, PCC is capable of performing "group" updates. With PCC
0162 the OS is capable of getting/setting the frequency of all the logical CPUs in
0163 the system with a single call to the BIOS.
0164
0165 1.1.1 Get Average Frequency:
0166 ----------------------------
0167 This command is used by the OSPM to query the running frequency of the
0168 processor since the last time this command was completed. The output buffer
0169 indicates the average unhalted frequency of the logical processor expressed as
0170 a percentage of the nominal (ie: maximum) CPU frequency. The output buffer
0171 also signifies if the CPU frequency is limited by a power budget condition.
0172
0173 1.1.2 Set Desired Frequency:
0174 ----------------------------
0175 This command is used by the OSPM to communicate to the platform firmware the
0176 desired frequency for a logical processor. The output buffer is currently
0177 ignored by OSPM. The next invocation of "Get Average Frequency" will inform
0178 OSPM if the desired frequency was achieved or not.
0179
0180 1.2 Platforms affected:
0181 -----------------------
0182 The PCC driver will load on any system where the platform firmware:
0183 * supports the PCC interface, and the associated PCCH() and PCCP() methods
0184 * assumes responsibility for managing the hardware clocking controls in order
0185 to deliver the requested processor performance
0186
0187 Currently, certain HP ProLiant platforms implement the PCC interface. On those
0188 platforms PCC is the "default" choice.
0189
0190 However, it is possible to disable this interface via a BIOS setting. In
0191 such an instance, as is also the case on platforms where the PCC interface
0192 is not implemented, the PCC driver will fail to load silently.
0193
0194 2. Driver and /sys details:
0195 ---------------------------
0196 When the driver loads, it merely prints the lowest and the highest CPU
0197 frequencies supported by the platform firmware.
0198
0199 The PCC driver loads with a message such as:
0200 pcc-cpufreq: (v1.00.00) driver loaded with frequency limits: 1600 MHz, 2933
0201 MHz
0202
0203 This means that the OPSM can request the CPU to run at any frequency in
0204 between the limits (1600 MHz, and 2933 MHz) specified in the message.
0205
0206 Internally, there is no need for the driver to convert the "target" frequency
0207 to a corresponding P-state.
0208
0209 The VERSION number for the driver will be of the format v.xy.ab.
0210 eg: 1.00.02
0211 ----- --
0212 | |
0213 | -- this will increase with bug fixes/enhancements to the driver
0214 |-- this is the version of the PCC specification the driver adheres to
0215
0216
0217 The following is a brief discussion on some of the fields exported via the
0218 /sys filesystem and how their values are affected by the PCC driver:
0219
0220 2.1 scaling_available_frequencies:
0221 ----------------------------------
0222 scaling_available_frequencies is not created in /sys. No intermediate
0223 frequencies need to be listed because the BIOS will try to achieve any
0224 frequency, within limits, requested by the governor. A frequency does not have
0225 to be strictly associated with a P-state.
0226
0227 2.2 cpuinfo_transition_latency:
0228 -------------------------------
0229 The cpuinfo_transition_latency field is 0. The PCC specification does
0230 not include a field to expose this value currently.
0231
0232 2.3 cpuinfo_cur_freq:
0233 ---------------------
0234 A) Often cpuinfo_cur_freq will show a value different than what is declared
0235 in the scaling_available_frequencies or scaling_cur_freq, or scaling_max_freq.
0236 This is due to "turbo boost" available on recent Intel processors. If certain
0237 conditions are met the BIOS can achieve a slightly higher speed than requested
0238 by OSPM. An example:
0239
0240 scaling_cur_freq : 2933000
0241 cpuinfo_cur_freq : 3196000
0242
0243 B) There is a round-off error associated with the cpuinfo_cur_freq value.
0244 Since the driver obtains the current frequency as a "percentage" (%) of the
0245 nominal frequency from the BIOS, sometimes, the values displayed by
0246 scaling_cur_freq and cpuinfo_cur_freq may not match. An example:
0247
0248 scaling_cur_freq : 1600000
0249 cpuinfo_cur_freq : 1583000
0250
0251 In this example, the nominal frequency is 2933 MHz. The driver obtains the
0252 current frequency, cpuinfo_cur_freq, as 54% of the nominal frequency:
0253
0254 54% of 2933 MHz = 1583 MHz
0255
0256 Nominal frequency is the maximum frequency of the processor, and it usually
0257 corresponds to the frequency of the P0 P-state.
0258
0259 2.4 related_cpus:
0260 -----------------
0261 The related_cpus field is identical to affected_cpus.
0262
0263 affected_cpus : 4
0264 related_cpus : 4
0265
0266 Currently, the PCC driver does not evaluate _PSD. The platforms that support
0267 PCC do not implement SW_ALL. So OSPM doesn't need to perform any coordination
0268 to ensure that the same frequency is requested of all dependent CPUs.
0269
0270 3. Caveats:
0271 -----------
0272 The "cpufreq_stats" module in its present form cannot be loaded and
0273 expected to work with the PCC driver. Since the "cpufreq_stats" module
0274 provides information wrt each P-state, it is not applicable to the PCC driver.
