.\" $NetBSD: acpicpu.4,v 1.35 2018/08/31 19:34:44 sevan Exp $
.\"
.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Neither the name of the author nor the names of any
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 31, 2018
.Dt ACPICPU 4
.Os
.Sh NAME
.Nm acpicpu
.Nd ACPI CPU
.Sh SYNOPSIS
.Cd "acpicpu* at cpu?"
.Sh DESCRIPTION
The
.Nm
device driver supports certain processor features that are
either only available via
.Tn ACPI
or that require
.Tn ACPI
to function properly.
Typically the
.Tn ACPI
processor functionality is grouped into so-called C-, P-, and T-states.
.Ss C-states
The processor power states, or C-states,
are low-power modes that can be used when the
.Tn CPU
is idle.
The idea is not new: already in the
.Tn 80486
processor a specific instruction
.Pq Tn HLT
was used for this purpose.
This was later accompanied by a pair of other instructions
.Pq Tn MONITOR , MWAIT .
By default,
.Nx
may use either one; see the
.Ic machdep.idle-mechanism
.Xr sysctl 8
variable.
.Tn ACPI
provides the latest amendment.
.Pp
The following C-states are typically available.
Additional processor or vendor specific
states (C4, ..., Cn) are handled internally by
.Nm .
.Bl -tag -width C1 -offset indent
.It Dv C0
This is the normal state of a processor; the
.Tn CPU
is busy executing instructions.
.It Dv C1
This is the state that is typically reached via the mentioned
.Tn x86
instructions.
On a typical processor,
.Dv C1
turns off the main internal
.Tn CPU
clock, leaving
.Tn APIC
running at full speed.
The
.Tn CPU
is free to temporarily leave the state to deal with important requests.
.It Dv C2
The main difference between
.Dv C1
and
.Dv C2
lies in the internal hardware entry method of the processor.
While less power is expected to be consumed than in
.Dv C1 ,
the bus interface unit is still running.
But depending on the processor, the local
.Tn APIC
timer may be stopped.
Like with
.Dv C1 ,
entering and exiting the state are expected to be fast operations.
.It Dv C3
This is the deepest conventional state.
Parts of the
.Tn CPU
are actively powered down.
The internal
.Tn CPU
clock is stopped.
The local
.Tn APIC
timer is stopped.
Depending on the processor, additional timers such as
.Xr x86/tsc 9
may be stopped.
Processor caches may be flushed.
Entry and exit latencies are expected to be high; the
.Tn CPU
can no longer
.Dq quickly
respond to bus activity or other interruptions.
.El
.Pp
Each state has a latency associated with entry and exit.
The higher the state, the lower the power consumption, and
the higher the potential performance costs.
.Pp
The
.Nm
driver tries to balance the latency
constraints when choosing the appropriate state.
One of the checks involves bus master activity;
if such activity is detected, a lower state is used.
It is known that particularly
.Xr usb 4
may cause high activity even when not in use.
If maximum power savings are desirable,
it may be necessary to use a custom kernel without
.Tn USB
support.
And generally: to save power with C-states, one should
avoid polling, both in userland and in the kernel.
.Ss P-states
The processor performance states, or P-states, are used to
control the clock frequencies and voltages of a
.Tn CPU .
Underneath the abstractions of
.Tn ACPI ,
P-states are associated with such technologies as
.Dq SpeedStep
.Pq Intel ,
.Dq PowerNow!
.Pq Tn AMD ,
and
.Dq PowerSaver
.Pq VIA .
.Pp
The P0-state is always the highest operating
frequency supported by the processor.
The number of additional P-states may vary across processors and vendors.
Each higher numbered P-state represents lower
clock frequencies and hence lower power consumption.
Note that while
.Nm
always uses the exact frequencies internally,
the user-visible values reported by
.Tn ACPI
may be rounded or approximated by the vendor.
.Pp
Unlike conventional
.Tn CPU
frequency management,
.Tn ACPI
provides support for Dynamic Voltage and Frequency Scaling
.Pq Tn DVFS .
Among other things,
this means that the firmware may request the implementation to
dynamically scale the presently supported maximum or minimum clock frequency.
For example, if
.Xr acpiacad 4
is disconnected, the maximum available frequency may be lowered.
By default,
the
.Nx
implementation may manipulate the frequencies
according to the notifications from the firmware.
.Ss T-states
Processor T-states, or
.Dq throttling states ,
can be used to actively modulate the
time a processor is allowed to execute.
Outside the
.Tn ACPI
nomenclature, throttling and T-states may be known as
.Dq on-demand clock modulation
.Pq Tn ODCM .
.Pp
The concept of
.Dq duty cycle
is relevant to T-states.
It is generally defined to be a fraction of time that a system is in an
.Dq active
state.
The T0-state has always a duty cycle of 100 \&%,
and thus, comparable to the C0-state, the processor is fully active.
Each additional higher-numbered T-state indicates lower duty cycles.
At most eight T-states may be available, although also T-states use
.Tn DVFS .
.Pp
The duty cycle does not refer to the actual clock signal,
but to the time period in which the clock signal is allowed
to drive the processor chip.
For instance, if a T-state has a duty cycle of 75 \&%, the
.Tn CPU
runs at the same clock frequency and uses the same voltage,
but 25 \&% of the time the
.Tn CPU
is forced to idle.
Because of this, the use of T-states may
severely affect system performance.
.Pp
There are two typical situations for throttling:
power management and thermal control.
As a technique to save power,
T-states are largely an artifact from the past.
There was a short period in the x86 lineage when P-states
were not yet available and throttling was considered
as an option to modulate the processor power consumption.
The approach was however quickly abandoned.
In modern x86 systems P-states should be preferred in all circumstances.
It is also more beneficial to move from the C0-state
to deeper C-states than it is to actively force down the
duty cycle of a processor.
.Pp
But T-states have retained their use as a last line
of defense against critical thermal conditions.
Many x86 processors include a catastrophic shutdown detector.
When the processor core temperature reaches this factory defined trip-point,
the processor execution is halted without any software control.
Before this fatal condition, it is possible to use throttling
for a short period of time in order to force the temperatures to lower levels.
The thermal control modulation is typically started only when
the system is in the highest-power P-state and
a high temperature situation exists.
After the temperatures have returned to non-critical levels,
the modulation ceases.
.Ss System Control Variables
The
.Nm
driver uses the same
.Xr sysctl 8
controls for P-states as the ones provided by
.Xr est 4
and
.Xr powernow 4 .
Depending on the processor, the second-level node is either
.Ic machdep.est
or
.Ic machdep.powernow .
Please note that future versions of
.Nm
may however remove these system control variables without further notice.
.Pp
In addition, the following two variables are available.
.Bl -tag -width "hw.acpi.cpu.dynamic" -offset indent
.It Ic hw.acpi.cpu.dynamic
A boolean that controls whether the states are allowed to change dynamically.
When enabled, C-, P-, and T-states may all change at runtime, and
.Nm
may also take actions based on requests from the firmware.
.It Ic hw.acpi.cpu.passive
A boolean that enables or disables automatic processor thermal management via
.Xr acpitz 4 .
.El
.Ss Statistics
The
.Nm
driver uses event counters to track the times
a processor has entered a given state.
It is possible to view the statistics by using
.Xr vmstat 1
(with the
.Fl e
flag).
.Sh SEE ALSO
.Xr acpi 4 ,
.Xr acpitz 4 ,
.Xr est 4 ,
.Xr odcm 4 ,
.Xr powernow 4 ,
.Xr cpu_idle 9
.Rs
.%A Etienne Le Sueur
.%A Gernot Heiser
.%T Dynamic Voltage and Frequency Scaling: The Laws of Diminishing Returns
.%O Proceedings of the 2010 Workshop on \
Power Aware Computing and Systems (HotPower'10)
.%D October, 2010
.%U http://www.ertos.nicta.com.au/publications/papers/LeSueur_Heiser_10.pdf
.Re
.Rs
.%A David C. Snowdon
.%T Operating System Directed Power Management
.%O PhD Thesis
.%I School of Computer Science and Engineering, University of New South Wales
.%D March, 2010
.%U http://ertos.nicta.com.au/publications/papers/Snowdon:phd.pdf
.Re
.Rs
.%A Microsoft Corporation
.%T Windows Native Processor Performance Control
.%N Version 1.1a
.%D November, 2002
.%U http://msdn.microsoft.com/en-us/windows/hardware/gg463343
.Re
.Rs
.%A Venkatesh Pallipadi
.%A Alexey Starikovskiy
.%T The Ondemand Governor. Past, Present, and Future
.%I Intel Open Source Technology Center
.%O Proceedings of the Linux Symposium
.%D July, 2006
.%U http://www.kernel.org/doc/ols/2006/ols2006v2-pages-223-238.pdf
.Re
.Sh HISTORY
The
.Nm
device driver appeared in
.Nx 6.0 .
.Sh AUTHORS
.An Jukka Ruohonen
.Aq jruohonen@iki.fi
.Sh CAVEATS
At least the following caveats can be mentioned.
.Bl -bullet
.It
It is currently only safe to use
.Dv C1
on
.Nx .
All other C-states are disabled by default.
.It
Processor thermal control (see
.Xr acpitz 4 )
is not yet supported.
.It
Depending on the processor, changes in C-, P-,
and T-states may all skew timers and counters such as
.Xr x86/tsc 9 .
This is neither handled by
.Nm
nor by
.Xr est 4
or
.Xr powernow 4 .
.It
There is currently neither a well-defined, machine-independent
.Tn API
for processor performance management nor a
.Dq governor
for different policies.
It is only possible to control the
.Tn CPU
frequencies from userland.
.El