Handbook - Config: Add cpu frequency control section

Differential Revision:  https://reviews.freebsd.org/D30004
Reviewed by:            allanjude@, bcr@, debdrup@, carlavilla@, Pau Amma <pauamma@gundo.com>
Approved by:            kib@, gjb@

1 files changed, 77 insertions, 0 deletions

diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc
index b82caf1419..f7d9cc27e2 100644
--- a/documentation/content/en/books/handbook/config/_index.adoc
+++ b/documentation/content/en/books/handbook/config/_index.adoc
@@ -1315,7 +1315,84 @@ And then enable the service executing the following command:
 # service powerd start
 ....
 
+[[cpufreq]]
+=== CPU Frequency Control
 
+FreeBSD includes a generic man:cpufreq[4] driver to allow the administrator, or software such as man:powerd[8] and package:sysutils/powerdxx[], to manage the frequency of the CPU to achieve the desired balance between performance and economy.
+A lower setting will save power while reducing the heat generated by the CPU.
+A higher setting will increase performance at the cost of using additional power and generating more heat.
+
+[[est]]
+=== Intel(R) Enhanced Speed Step(TM)
+
+The Intel(R) Enhanced Speed Step(TM) driver, man:est[4], replaces the generic man:cpufreq[4] driver for CPUs that provide this feature.
+The CPU frequency can be statically adjusted using man:sysctl[8], or with the `/etc/rc.d/power_profile` startup script.
+Additional software, such as man:powerd[8] or package:sysutils/powerdxx[], can be used to automatically adjust the CPU frequency based on processor utilization.
+
+Each supported frequency, along with its expected power consumption, can be listed by examining the man:sysctl[3] tree:
+
+[source,shell]
+....
+# sysctl dev.cpufreq.0.freq_driver dev.cpu.0.freq_levels dev.cpu.0.freq
+....
+
+The output should be similar to the following:
+
+[.programlisting]
+....
+dev.cpufreq.0.freq_driver: est0
+dev.cpu.0.freq_levels: 3001/53000 3000/53000 2900/50301 2700/46082 2600/43525 2400/39557 2300/37137 2100/33398 2000/31112 1800/27610 1700/25455 1500/22171 1400/20144 1200/17084 1100/15181 900/12329 800/10550
+dev.cpu.0.freq: 800
+....
+
+A frequency 1 MHz higher than the maximum frequency of the CPU indicates the Intel(R) Turbo Boost(TM) feature.
+
+[[hwpstate_intel]]
+=== Intel Speed Shift(TM)
+
+Users running newer Intel(R) CPUs may find some differences in dynamic frequency control when upgrading to FreeBSD 13.
+A new driver for the Intel(R) Speed Shift(TM) feature set, available on certain SKUs, exposes the ability for the hardware to dynamically vary the core frequencies, including on a per core basis.
+FreeBSD 13 comes with the man:hwpstate_intel[4] driver to automatically enable Speed Shift(TM) control on equipped CPUs, replacing the older Enhanced Speed Step(TM) man:est[4] driver.
+The man:sysctl[8] `dev.cpufreq.%d.freq_driver` will indicate if the system is using Speed Shift.
+
+To determine which frequency control driver is being used, examining the `dev.cpufreq.0.freq_driver` oid.
+
+[source,shell]
+....
+# sysctl dev.cpufreq.0.freq_driver
+....
+
+The output should be similar to the following:
+
+[.programlisting]
+....
+dev.cpufreq.0.freq_driver: hwpstate_intel0
+....
+
+This indicates that the new man:hwpstate_intel[4] driver is in use.
+On such systems, the oid `dev.cpu.%d.freq_levels` will show only the maximum CPU frequency, and will indicate a power consumption level of `-1`.
+
+The current CPU frequency can be determined by examining the `dev.cpu.%d.freq` oid.
+
+[source,shell]
+....
+# sysctl dev.cpu.0.freq_levels dev.cpu.0.freq
+....
+
+The output should be similar to the following:
+
+[.programlisting]
+....
+dev.cpu.0.freq_levels: 3696/-1
+dev.cpu.0.freq: 898
+....
+
+For more information, including on how to balance performance and energy use, and on how to disable this driver, refer to the man page man:hwpstate_intel[4].
+
+[NOTE]
+====
+Users accustomed to using man:powerd[8] or package:sysutils/powerdxx[] will find these utilities have been superseded by the man:hwpstate_intel[4] driver and no longer work as expected.
+====
 
 [[graphics-card-power-management]]
 === Graphics Card Power Management