cpufreq.rst 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708
  1. .. SPDX-License-Identifier: GPL-2.0
  2. .. include:: <isonum.txt>
  3. .. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>`
  4. =======================
  5. CPU Performance Scaling
  6. =======================
  7. :Copyright: |copy| 2017 Intel Corporation
  8. :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
  9. The Concept of CPU Performance Scaling
  10. ======================================
  11. The majority of modern processors are capable of operating in a number of
  12. different clock frequency and voltage configurations, often referred to as
  13. Operating Performance Points or P-states (in ACPI terminology). As a rule,
  14. the higher the clock frequency and the higher the voltage, the more instructions
  15. can be retired by the CPU over a unit of time, but also the higher the clock
  16. frequency and the higher the voltage, the more energy is consumed over a unit of
  17. time (or the more power is drawn) by the CPU in the given P-state. Therefore
  18. there is a natural tradeoff between the CPU capacity (the number of instructions
  19. that can be executed over a unit of time) and the power drawn by the CPU.
  20. In some situations it is desirable or even necessary to run the program as fast
  21. as possible and then there is no reason to use any P-states different from the
  22. highest one (i.e. the highest-performance frequency/voltage configuration
  23. available). In some other cases, however, it may not be necessary to execute
  24. instructions so quickly and maintaining the highest available CPU capacity for a
  25. relatively long time without utilizing it entirely may be regarded as wasteful.
  26. It also may not be physically possible to maintain maximum CPU capacity for too
  27. long for thermal or power supply capacity reasons or similar. To cover those
  28. cases, there are hardware interfaces allowing CPUs to be switched between
  29. different frequency/voltage configurations or (in the ACPI terminology) to be
  30. put into different P-states.
  31. Typically, they are used along with algorithms to estimate the required CPU
  32. capacity, so as to decide which P-states to put the CPUs into. Of course, since
  33. the utilization of the system generally changes over time, that has to be done
  34. repeatedly on a regular basis. The activity by which this happens is referred
  35. to as CPU performance scaling or CPU frequency scaling (because it involves
  36. adjusting the CPU clock frequency).
  37. CPU Performance Scaling in Linux
  38. ================================
  39. The Linux kernel supports CPU performance scaling by means of the ``CPUFreq``
  40. (CPU Frequency scaling) subsystem that consists of three layers of code: the
  41. core, scaling governors and scaling drivers.
  42. The ``CPUFreq`` core provides the common code infrastructure and user space
  43. interfaces for all platforms that support CPU performance scaling. It defines
  44. the basic framework in which the other components operate.
  45. Scaling governors implement algorithms to estimate the required CPU capacity.
  46. As a rule, each governor implements one, possibly parametrized, scaling
  47. algorithm.
  48. Scaling drivers talk to the hardware. They provide scaling governors with
  49. information on the available P-states (or P-state ranges in some cases) and
  50. access platform-specific hardware interfaces to change CPU P-states as requested
  51. by scaling governors.
  52. In principle, all available scaling governors can be used with every scaling
  53. driver. That design is based on the observation that the information used by
  54. performance scaling algorithms for P-state selection can be represented in a
  55. platform-independent form in the majority of cases, so it should be possible
  56. to use the same performance scaling algorithm implemented in exactly the same
  57. way regardless of which scaling driver is used. Consequently, the same set of
  58. scaling governors should be suitable for every supported platform.
  59. However, that observation may not hold for performance scaling algorithms
  60. based on information provided by the hardware itself, for example through
  61. feedback registers, as that information is typically specific to the hardware
  62. interface it comes from and may not be easily represented in an abstract,
  63. platform-independent way. For this reason, ``CPUFreq`` allows scaling drivers
  64. to bypass the governor layer and implement their own performance scaling
  65. algorithms. That is done by the |intel_pstate| scaling driver.
  66. ``CPUFreq`` Policy Objects
  67. ==========================
  68. In some cases the hardware interface for P-state control is shared by multiple
  69. CPUs. That is, for example, the same register (or set of registers) is used to
  70. control the P-state of multiple CPUs at the same time and writing to it affects
  71. all of those CPUs simultaneously.
  72. Sets of CPUs sharing hardware P-state control interfaces are represented by
  73. ``CPUFreq`` as struct cpufreq_policy objects. For consistency,
  74. struct cpufreq_policy is also used when there is only one CPU in the given
  75. set.
  76. The ``CPUFreq`` core maintains a pointer to a struct cpufreq_policy object for
  77. every CPU in the system, including CPUs that are currently offline. If multiple
  78. CPUs share the same hardware P-state control interface, all of the pointers
  79. corresponding to them point to the same struct cpufreq_policy object.
  80. ``CPUFreq`` uses struct cpufreq_policy as its basic data type and the design
  81. of its user space interface is based on the policy concept.
  82. CPU Initialization
  83. ==================
  84. First of all, a scaling driver has to be registered for ``CPUFreq`` to work.
  85. It is only possible to register one scaling driver at a time, so the scaling
  86. driver is expected to be able to handle all CPUs in the system.
  87. The scaling driver may be registered before or after CPU registration. If
  88. CPUs are registered earlier, the driver core invokes the ``CPUFreq`` core to
  89. take a note of all of the already registered CPUs during the registration of the
  90. scaling driver. In turn, if any CPUs are registered after the registration of
  91. the scaling driver, the ``CPUFreq`` core will be invoked to take note of them
  92. at their registration time.
  93. In any case, the ``CPUFreq`` core is invoked to take note of any logical CPU it
  94. has not seen so far as soon as it is ready to handle that CPU. [Note that the
  95. logical CPU may be a physical single-core processor, or a single core in a
  96. multicore processor, or a hardware thread in a physical processor or processor
  97. core. In what follows "CPU" always means "logical CPU" unless explicitly stated
  98. otherwise and the word "processor" is used to refer to the physical part
  99. possibly including multiple logical CPUs.]
  100. Once invoked, the ``CPUFreq`` core checks if the policy pointer is already set
  101. for the given CPU and if so, it skips the policy object creation. Otherwise,
  102. a new policy object is created and initialized, which involves the creation of
  103. a new policy directory in ``sysfs``, and the policy pointer corresponding to
  104. the given CPU is set to the new policy object's address in memory.
  105. Next, the scaling driver's ``->init()`` callback is invoked with the policy
  106. pointer of the new CPU passed to it as the argument. That callback is expected
  107. to initialize the performance scaling hardware interface for the given CPU (or,
  108. more precisely, for the set of CPUs sharing the hardware interface it belongs
  109. to, represented by its policy object) and, if the policy object it has been
  110. called for is new, to set parameters of the policy, like the minimum and maximum
  111. frequencies supported by the hardware, the table of available frequencies (if
  112. the set of supported P-states is not a continuous range), and the mask of CPUs
  113. that belong to the same policy (including both online and offline CPUs). That
  114. mask is then used by the core to populate the policy pointers for all of the
  115. CPUs in it.
  116. The next major initialization step for a new policy object is to attach a
  117. scaling governor to it (to begin with, that is the default scaling governor
  118. determined by the kernel command line or configuration, but it may be changed
  119. later via ``sysfs``). First, a pointer to the new policy object is passed to
  120. the governor's ``->init()`` callback which is expected to initialize all of the
  121. data structures necessary to handle the given policy and, possibly, to add
  122. a governor ``sysfs`` interface to it. Next, the governor is started by
  123. invoking its ``->start()`` callback.
  124. That callback is expected to register per-CPU utilization update callbacks for
  125. all of the online CPUs belonging to the given policy with the CPU scheduler.
  126. The utilization update callbacks will be invoked by the CPU scheduler on
  127. important events, like task enqueue and dequeue, on every iteration of the
  128. scheduler tick or generally whenever the CPU utilization may change (from the
  129. scheduler's perspective). They are expected to carry out computations needed
  130. to determine the P-state to use for the given policy going forward and to
  131. invoke the scaling driver to make changes to the hardware in accordance with
  132. the P-state selection. The scaling driver may be invoked directly from
  133. scheduler context or asynchronously, via a kernel thread or workqueue, depending
  134. on the configuration and capabilities of the scaling driver and the governor.
  135. Similar steps are taken for policy objects that are not new, but were "inactive"
  136. previously, meaning that all of the CPUs belonging to them were offline. The
  137. only practical difference in that case is that the ``CPUFreq`` core will attempt
  138. to use the scaling governor previously used with the policy that became
  139. "inactive" (and is re-initialized now) instead of the default governor.
  140. In turn, if a previously offline CPU is being brought back online, but some
  141. other CPUs sharing the policy object with it are online already, there is no
  142. need to re-initialize the policy object at all. In that case, it only is
  143. necessary to restart the scaling governor so that it can take the new online CPU
  144. into account. That is achieved by invoking the governor's ``->stop`` and
  145. ``->start()`` callbacks, in this order, for the entire policy.
  146. As mentioned before, the |intel_pstate| scaling driver bypasses the scaling
  147. governor layer of ``CPUFreq`` and provides its own P-state selection algorithms.
  148. Consequently, if |intel_pstate| is used, scaling governors are not attached to
  149. new policy objects. Instead, the driver's ``->setpolicy()`` callback is invoked
  150. to register per-CPU utilization update callbacks for each policy. These
  151. callbacks are invoked by the CPU scheduler in the same way as for scaling
  152. governors, but in the |intel_pstate| case they both determine the P-state to
  153. use and change the hardware configuration accordingly in one go from scheduler
  154. context.
  155. The policy objects created during CPU initialization and other data structures
  156. associated with them are torn down when the scaling driver is unregistered
  157. (which happens when the kernel module containing it is unloaded, for example) or
  158. when the last CPU belonging to the given policy in unregistered.
  159. Policy Interface in ``sysfs``
  160. =============================
  161. During the initialization of the kernel, the ``CPUFreq`` core creates a
  162. ``sysfs`` directory (kobject) called ``cpufreq`` under
  163. :file:`/sys/devices/system/cpu/`.
  164. That directory contains a ``policyX`` subdirectory (where ``X`` represents an
  165. integer number) for every policy object maintained by the ``CPUFreq`` core.
  166. Each ``policyX`` directory is pointed to by ``cpufreq`` symbolic links
  167. under :file:`/sys/devices/system/cpu/cpuY/` (where ``Y`` represents an integer
  168. that may be different from the one represented by ``X``) for all of the CPUs
  169. associated with (or belonging to) the given policy. The ``policyX`` directories
  170. in :file:`/sys/devices/system/cpu/cpufreq` each contain policy-specific
  171. attributes (files) to control ``CPUFreq`` behavior for the corresponding policy
  172. objects (that is, for all of the CPUs associated with them).
  173. Some of those attributes are generic. They are created by the ``CPUFreq`` core
  174. and their behavior generally does not depend on what scaling driver is in use
  175. and what scaling governor is attached to the given policy. Some scaling drivers
  176. also add driver-specific attributes to the policy directories in ``sysfs`` to
  177. control policy-specific aspects of driver behavior.
  178. The generic attributes under :file:`/sys/devices/system/cpu/cpufreq/policyX/`
  179. are the following:
  180. ``affected_cpus``
  181. List of online CPUs belonging to this policy (i.e. sharing the hardware
  182. performance scaling interface represented by the ``policyX`` policy
  183. object).
  184. ``bios_limit``
  185. If the platform firmware (BIOS) tells the OS to apply an upper limit to
  186. CPU frequencies, that limit will be reported through this attribute (if
  187. present).
  188. The existence of the limit may be a result of some (often unintentional)
  189. BIOS settings, restrictions coming from a service processor or another
  190. BIOS/HW-based mechanisms.
  191. This does not cover ACPI thermal limitations which can be discovered
  192. through a generic thermal driver.
  193. This attribute is not present if the scaling driver in use does not
  194. support it.
  195. ``cpuinfo_cur_freq``
  196. Current frequency of the CPUs belonging to this policy as obtained from
  197. the hardware (in KHz).
  198. This is expected to be the frequency the hardware actually runs at.
  199. If that frequency cannot be determined, this attribute should not
  200. be present.
  201. ``cpuinfo_max_freq``
  202. Maximum possible operating frequency the CPUs belonging to this policy
  203. can run at (in kHz).
  204. ``cpuinfo_min_freq``
  205. Minimum possible operating frequency the CPUs belonging to this policy
  206. can run at (in kHz).
  207. ``cpuinfo_transition_latency``
  208. The time it takes to switch the CPUs belonging to this policy from one
  209. P-state to another, in nanoseconds.
  210. If unknown or if known to be so high that the scaling driver does not
  211. work with the `ondemand`_ governor, -1 (:c:macro:`CPUFREQ_ETERNAL`)
  212. will be returned by reads from this attribute.
  213. ``related_cpus``
  214. List of all (online and offline) CPUs belonging to this policy.
  215. ``scaling_available_governors``
  216. List of ``CPUFreq`` scaling governors present in the kernel that can
  217. be attached to this policy or (if the |intel_pstate| scaling driver is
  218. in use) list of scaling algorithms provided by the driver that can be
  219. applied to this policy.
  220. [Note that some governors are modular and it may be necessary to load a
  221. kernel module for the governor held by it to become available and be
  222. listed by this attribute.]
  223. ``scaling_cur_freq``
  224. Current frequency of all of the CPUs belonging to this policy (in kHz).
  225. In the majority of cases, this is the frequency of the last P-state
  226. requested by the scaling driver from the hardware using the scaling
  227. interface provided by it, which may or may not reflect the frequency
  228. the CPU is actually running at (due to hardware design and other
  229. limitations).
  230. Some architectures (e.g. ``x86``) may attempt to provide information
  231. more precisely reflecting the current CPU frequency through this
  232. attribute, but that still may not be the exact current CPU frequency as
  233. seen by the hardware at the moment.
  234. ``scaling_driver``
  235. The scaling driver currently in use.
  236. ``scaling_governor``
  237. The scaling governor currently attached to this policy or (if the
  238. |intel_pstate| scaling driver is in use) the scaling algorithm
  239. provided by the driver that is currently applied to this policy.
  240. This attribute is read-write and writing to it will cause a new scaling
  241. governor to be attached to this policy or a new scaling algorithm
  242. provided by the scaling driver to be applied to it (in the
  243. |intel_pstate| case), as indicated by the string written to this
  244. attribute (which must be one of the names listed by the
  245. ``scaling_available_governors`` attribute described above).
  246. ``scaling_max_freq``
  247. Maximum frequency the CPUs belonging to this policy are allowed to be
  248. running at (in kHz).
  249. This attribute is read-write and writing a string representing an
  250. integer to it will cause a new limit to be set (it must not be lower
  251. than the value of the ``scaling_min_freq`` attribute).
  252. ``scaling_min_freq``
  253. Minimum frequency the CPUs belonging to this policy are allowed to be
  254. running at (in kHz).
  255. This attribute is read-write and writing a string representing a
  256. non-negative integer to it will cause a new limit to be set (it must not
  257. be higher than the value of the ``scaling_max_freq`` attribute).
  258. ``scaling_setspeed``
  259. This attribute is functional only if the `userspace`_ scaling governor
  260. is attached to the given policy.
  261. It returns the last frequency requested by the governor (in kHz) or can
  262. be written to in order to set a new frequency for the policy.
  263. Generic Scaling Governors
  264. =========================
  265. ``CPUFreq`` provides generic scaling governors that can be used with all
  266. scaling drivers. As stated before, each of them implements a single, possibly
  267. parametrized, performance scaling algorithm.
  268. Scaling governors are attached to policy objects and different policy objects
  269. can be handled by different scaling governors at the same time (although that
  270. may lead to suboptimal results in some cases).
  271. The scaling governor for a given policy object can be changed at any time with
  272. the help of the ``scaling_governor`` policy attribute in ``sysfs``.
  273. Some governors expose ``sysfs`` attributes to control or fine-tune the scaling
  274. algorithms implemented by them. Those attributes, referred to as governor
  275. tunables, can be either global (system-wide) or per-policy, depending on the
  276. scaling driver in use. If the driver requires governor tunables to be
  277. per-policy, they are located in a subdirectory of each policy directory.
  278. Otherwise, they are located in a subdirectory under
  279. :file:`/sys/devices/system/cpu/cpufreq/`. In either case the name of the
  280. subdirectory containing the governor tunables is the name of the governor
  281. providing them.
  282. ``performance``
  283. ---------------
  284. When attached to a policy object, this governor causes the highest frequency,
  285. within the ``scaling_max_freq`` policy limit, to be requested for that policy.
  286. The request is made once at that time the governor for the policy is set to
  287. ``performance`` and whenever the ``scaling_max_freq`` or ``scaling_min_freq``
  288. policy limits change after that.
  289. ``powersave``
  290. -------------
  291. When attached to a policy object, this governor causes the lowest frequency,
  292. within the ``scaling_min_freq`` policy limit, to be requested for that policy.
  293. The request is made once at that time the governor for the policy is set to
  294. ``powersave`` and whenever the ``scaling_max_freq`` or ``scaling_min_freq``
  295. policy limits change after that.
  296. ``userspace``
  297. -------------
  298. This governor does not do anything by itself. Instead, it allows user space
  299. to set the CPU frequency for the policy it is attached to by writing to the
  300. ``scaling_setspeed`` attribute of that policy.
  301. ``schedutil``
  302. -------------
  303. This governor uses CPU utilization data available from the CPU scheduler. It
  304. generally is regarded as a part of the CPU scheduler, so it can access the
  305. scheduler's internal data structures directly.
  306. It runs entirely in scheduler context, although in some cases it may need to
  307. invoke the scaling driver asynchronously when it decides that the CPU frequency
  308. should be changed for a given policy (that depends on whether or not the driver
  309. is capable of changing the CPU frequency from scheduler context).
  310. The actions of this governor for a particular CPU depend on the scheduling class
  311. invoking its utilization update callback for that CPU. If it is invoked by the
  312. RT or deadline scheduling classes, the governor will increase the frequency to
  313. the allowed maximum (that is, the ``scaling_max_freq`` policy limit). In turn,
  314. if it is invoked by the CFS scheduling class, the governor will use the
  315. Per-Entity Load Tracking (PELT) metric for the root control group of the
  316. given CPU as the CPU utilization estimate (see the *Per-entity load tracking*
  317. LWN.net article [1]_ for a description of the PELT mechanism). Then, the new
  318. CPU frequency to apply is computed in accordance with the formula
  319. f = 1.25 * ``f_0`` * ``util`` / ``max``
  320. where ``util`` is the PELT number, ``max`` is the theoretical maximum of
  321. ``util``, and ``f_0`` is either the maximum possible CPU frequency for the given
  322. policy (if the PELT number is frequency-invariant), or the current CPU frequency
  323. (otherwise).
  324. This governor also employs a mechanism allowing it to temporarily bump up the
  325. CPU frequency for tasks that have been waiting on I/O most recently, called
  326. "IO-wait boosting". That happens when the :c:macro:`SCHED_CPUFREQ_IOWAIT` flag
  327. is passed by the scheduler to the governor callback which causes the frequency
  328. to go up to the allowed maximum immediately and then draw back to the value
  329. returned by the above formula over time.
  330. This governor exposes only one tunable:
  331. ``rate_limit_us``
  332. Minimum time (in microseconds) that has to pass between two consecutive
  333. runs of governor computations (default: 1000 times the scaling driver's
  334. transition latency).
  335. The purpose of this tunable is to reduce the scheduler context overhead
  336. of the governor which might be excessive without it.
  337. This governor generally is regarded as a replacement for the older `ondemand`_
  338. and `conservative`_ governors (described below), as it is simpler and more
  339. tightly integrated with the CPU scheduler, its overhead in terms of CPU context
  340. switches and similar is less significant, and it uses the scheduler's own CPU
  341. utilization metric, so in principle its decisions should not contradict the
  342. decisions made by the other parts of the scheduler.
  343. ``ondemand``
  344. ------------
  345. This governor uses CPU load as a CPU frequency selection metric.
  346. In order to estimate the current CPU load, it measures the time elapsed between
  347. consecutive invocations of its worker routine and computes the fraction of that
  348. time in which the given CPU was not idle. The ratio of the non-idle (active)
  349. time to the total CPU time is taken as an estimate of the load.
  350. If this governor is attached to a policy shared by multiple CPUs, the load is
  351. estimated for all of them and the greatest result is taken as the load estimate
  352. for the entire policy.
  353. The worker routine of this governor has to run in process context, so it is
  354. invoked asynchronously (via a workqueue) and CPU P-states are updated from
  355. there if necessary. As a result, the scheduler context overhead from this
  356. governor is minimum, but it causes additional CPU context switches to happen
  357. relatively often and the CPU P-state updates triggered by it can be relatively
  358. irregular. Also, it affects its own CPU load metric by running code that
  359. reduces the CPU idle time (even though the CPU idle time is only reduced very
  360. slightly by it).
  361. It generally selects CPU frequencies proportional to the estimated load, so that
  362. the value of the ``cpuinfo_max_freq`` policy attribute corresponds to the load of
  363. 1 (or 100%), and the value of the ``cpuinfo_min_freq`` policy attribute
  364. corresponds to the load of 0, unless when the load exceeds a (configurable)
  365. speedup threshold, in which case it will go straight for the highest frequency
  366. it is allowed to use (the ``scaling_max_freq`` policy limit).
  367. This governor exposes the following tunables:
  368. ``sampling_rate``
  369. This is how often the governor's worker routine should run, in
  370. microseconds.
  371. Typically, it is set to values of the order of 10000 (10 ms). Its
  372. default value is equal to the value of ``cpuinfo_transition_latency``
  373. for each policy this governor is attached to (but since the unit here
  374. is greater by 1000, this means that the time represented by
  375. ``sampling_rate`` is 1000 times greater than the transition latency by
  376. default).
  377. If this tunable is per-policy, the following shell command sets the time
  378. represented by it to be 750 times as high as the transition latency::
  379. # echo `$(($(cat cpuinfo_transition_latency) * 750 / 1000)) > ondemand/sampling_rate
  380. ``up_threshold``
  381. If the estimated CPU load is above this value (in percent), the governor
  382. will set the frequency to the maximum value allowed for the policy.
  383. Otherwise, the selected frequency will be proportional to the estimated
  384. CPU load.
  385. ``ignore_nice_load``
  386. If set to 1 (default 0), it will cause the CPU load estimation code to
  387. treat the CPU time spent on executing tasks with "nice" levels greater
  388. than 0 as CPU idle time.
  389. This may be useful if there are tasks in the system that should not be
  390. taken into account when deciding what frequency to run the CPUs at.
  391. Then, to make that happen it is sufficient to increase the "nice" level
  392. of those tasks above 0 and set this attribute to 1.
  393. ``sampling_down_factor``
  394. Temporary multiplier, between 1 (default) and 100 inclusive, to apply to
  395. the ``sampling_rate`` value if the CPU load goes above ``up_threshold``.
  396. This causes the next execution of the governor's worker routine (after
  397. setting the frequency to the allowed maximum) to be delayed, so the
  398. frequency stays at the maximum level for a longer time.
  399. Frequency fluctuations in some bursty workloads may be avoided this way
  400. at the cost of additional energy spent on maintaining the maximum CPU
  401. capacity.
  402. ``powersave_bias``
  403. Reduction factor to apply to the original frequency target of the
  404. governor (including the maximum value used when the ``up_threshold``
  405. value is exceeded by the estimated CPU load) or sensitivity threshold
  406. for the AMD frequency sensitivity powersave bias driver
  407. (:file:`drivers/cpufreq/amd_freq_sensitivity.c`), between 0 and 1000
  408. inclusive.
  409. If the AMD frequency sensitivity powersave bias driver is not loaded,
  410. the effective frequency to apply is given by
  411. f * (1 - ``powersave_bias`` / 1000)
  412. where f is the governor's original frequency target. The default value
  413. of this attribute is 0 in that case.
  414. If the AMD frequency sensitivity powersave bias driver is loaded, the
  415. value of this attribute is 400 by default and it is used in a different
  416. way.
  417. On Family 16h (and later) AMD processors there is a mechanism to get a
  418. measured workload sensitivity, between 0 and 100% inclusive, from the
  419. hardware. That value can be used to estimate how the performance of the
  420. workload running on a CPU will change in response to frequency changes.
  421. The performance of a workload with the sensitivity of 0 (memory-bound or
  422. IO-bound) is not expected to increase at all as a result of increasing
  423. the CPU frequency, whereas workloads with the sensitivity of 100%
  424. (CPU-bound) are expected to perform much better if the CPU frequency is
  425. increased.
  426. If the workload sensitivity is less than the threshold represented by
  427. the ``powersave_bias`` value, the sensitivity powersave bias driver
  428. will cause the governor to select a frequency lower than its original
  429. target, so as to avoid over-provisioning workloads that will not benefit
  430. from running at higher CPU frequencies.
  431. ``conservative``
  432. ----------------
  433. This governor uses CPU load as a CPU frequency selection metric.
  434. It estimates the CPU load in the same way as the `ondemand`_ governor described
  435. above, but the CPU frequency selection algorithm implemented by it is different.
  436. Namely, it avoids changing the frequency significantly over short time intervals
  437. which may not be suitable for systems with limited power supply capacity (e.g.
  438. battery-powered). To achieve that, it changes the frequency in relatively
  439. small steps, one step at a time, up or down - depending on whether or not a
  440. (configurable) threshold has been exceeded by the estimated CPU load.
  441. This governor exposes the following tunables:
  442. ``freq_step``
  443. Frequency step in percent of the maximum frequency the governor is
  444. allowed to set (the ``scaling_max_freq`` policy limit), between 0 and
  445. 100 (5 by default).
  446. This is how much the frequency is allowed to change in one go. Setting
  447. it to 0 will cause the default frequency step (5 percent) to be used
  448. and setting it to 100 effectively causes the governor to periodically
  449. switch the frequency between the ``scaling_min_freq`` and
  450. ``scaling_max_freq`` policy limits.
  451. ``down_threshold``
  452. Threshold value (in percent, 20 by default) used to determine the
  453. frequency change direction.
  454. If the estimated CPU load is greater than this value, the frequency will
  455. go up (by ``freq_step``). If the load is less than this value (and the
  456. ``sampling_down_factor`` mechanism is not in effect), the frequency will
  457. go down. Otherwise, the frequency will not be changed.
  458. ``sampling_down_factor``
  459. Frequency decrease deferral factor, between 1 (default) and 10
  460. inclusive.
  461. It effectively causes the frequency to go down ``sampling_down_factor``
  462. times slower than it ramps up.
  463. Frequency Boost Support
  464. =======================
  465. Background
  466. ----------
  467. Some processors support a mechanism to raise the operating frequency of some
  468. cores in a multicore package temporarily (and above the sustainable frequency
  469. threshold for the whole package) under certain conditions, for example if the
  470. whole chip is not fully utilized and below its intended thermal or power budget.
  471. Different names are used by different vendors to refer to this functionality.
  472. For Intel processors it is referred to as "Turbo Boost", AMD calls it
  473. "Turbo-Core" or (in technical documentation) "Core Performance Boost" and so on.
  474. As a rule, it also is implemented differently by different vendors. The simple
  475. term "frequency boost" is used here for brevity to refer to all of those
  476. implementations.
  477. The frequency boost mechanism may be either hardware-based or software-based.
  478. If it is hardware-based (e.g. on x86), the decision to trigger the boosting is
  479. made by the hardware (although in general it requires the hardware to be put
  480. into a special state in which it can control the CPU frequency within certain
  481. limits). If it is software-based (e.g. on ARM), the scaling driver decides
  482. whether or not to trigger boosting and when to do that.
  483. The ``boost`` File in ``sysfs``
  484. -------------------------------
  485. This file is located under :file:`/sys/devices/system/cpu/cpufreq/` and controls
  486. the "boost" setting for the whole system. It is not present if the underlying
  487. scaling driver does not support the frequency boost mechanism (or supports it,
  488. but provides a driver-specific interface for controlling it, like
  489. |intel_pstate|).
  490. If the value in this file is 1, the frequency boost mechanism is enabled. This
  491. means that either the hardware can be put into states in which it is able to
  492. trigger boosting (in the hardware-based case), or the software is allowed to
  493. trigger boosting (in the software-based case). It does not mean that boosting
  494. is actually in use at the moment on any CPUs in the system. It only means a
  495. permission to use the frequency boost mechanism (which still may never be used
  496. for other reasons).
  497. If the value in this file is 0, the frequency boost mechanism is disabled and
  498. cannot be used at all.
  499. The only values that can be written to this file are 0 and 1.
  500. Rationale for Boost Control Knob
  501. --------------------------------
  502. The frequency boost mechanism is generally intended to help to achieve optimum
  503. CPU performance on time scales below software resolution (e.g. below the
  504. scheduler tick interval) and it is demonstrably suitable for many workloads, but
  505. it may lead to problems in certain situations.
  506. For this reason, many systems make it possible to disable the frequency boost
  507. mechanism in the platform firmware (BIOS) setup, but that requires the system to
  508. be restarted for the setting to be adjusted as desired, which may not be
  509. practical at least in some cases. For example:
  510. 1. Boosting means overclocking the processor, although under controlled
  511. conditions. Generally, the processor's energy consumption increases
  512. as a result of increasing its frequency and voltage, even temporarily.
  513. That may not be desirable on systems that switch to power sources of
  514. limited capacity, such as batteries, so the ability to disable the boost
  515. mechanism while the system is running may help there (but that depends on
  516. the workload too).
  517. 2. In some situations deterministic behavior is more important than
  518. performance or energy consumption (or both) and the ability to disable
  519. boosting while the system is running may be useful then.
  520. 3. To examine the impact of the frequency boost mechanism itself, it is useful
  521. to be able to run tests with and without boosting, preferably without
  522. restarting the system in the meantime.
  523. 4. Reproducible results are important when running benchmarks. Since
  524. the boosting functionality depends on the load of the whole package,
  525. single-thread performance may vary because of it which may lead to
  526. unreproducible results sometimes. That can be avoided by disabling the
  527. frequency boost mechanism before running benchmarks sensitive to that
  528. issue.
  529. Legacy AMD ``cpb`` Knob
  530. -----------------------
  531. The AMD powernow-k8 scaling driver supports a ``sysfs`` knob very similar to
  532. the global ``boost`` one. It is used for disabling/enabling the "Core
  533. Performance Boost" feature of some AMD processors.
  534. If present, that knob is located in every ``CPUFreq`` policy directory in
  535. ``sysfs`` (:file:`/sys/devices/system/cpu/cpufreq/policyX/`) and is called
  536. ``cpb``, which indicates a more fine grained control interface. The actual
  537. implementation, however, works on the system-wide basis and setting that knob
  538. for one policy causes the same value of it to be set for all of the other
  539. policies at the same time.
  540. That knob is still supported on AMD processors that support its underlying
  541. hardware feature, but it may be configured out of the kernel (via the
  542. :c:macro:`CONFIG_X86_ACPI_CPUFREQ_CPB` configuration option) and the global
  543. ``boost`` knob is present regardless. Thus it is always possible use the
  544. ``boost`` knob instead of the ``cpb`` one which is highly recommended, as that
  545. is more consistent with what all of the other systems do (and the ``cpb`` knob
  546. may not be supported any more in the future).
  547. The ``cpb`` knob is never present for any processors without the underlying
  548. hardware feature (e.g. all Intel ones), even if the
  549. :c:macro:`CONFIG_X86_ACPI_CPUFREQ_CPB` configuration option is set.
  550. References
  551. ==========
  552. .. [1] Jonathan Corbet, *Per-entity load tracking*,
  553. https://lwn.net/Articles/531853/