.\" $NetBSD: acpitz.4,v 1.14 2014/03/18 18:20:39 riastradh Exp $
.\"
.\" Copyright (c) 2003, 2004, 2011 The NetBSD Foundation, Inc.
.\" 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. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 January 9, 2011
.Dt ACPITZ 4
.Os
.Sh NAME
.Nm acpitz
.Nd ACPI Thermal Zone
.Sh SYNOPSIS
.Cd "acpitz* at acpi?"
.Sh DESCRIPTION
The
.Nm
driver supports so-called
.Tn ACPI
.Dq Thermal Zones .
The temperature can be monitored by the
.Xr envsys 4
API or the
.Xr envstat 8
command.
.Pp
The distinction between
.Dq active
and
.Dq passive
cooling is central to the abstractions behind
.Nm .
These are inversely related to each other:
.Bl -enum -offset 2n
.It
Active cooling means that the system increases the power consumption of the
machine by performing active thermal management (for example, by turning on
a fan) in order to reduce the temperatures.
.It
Passive cooling means that the system reduces the power consumption of
devices at the cost of system performance (for example, by lowering the
.Tn CPU
frequencies) in order to reduce the temperatures.
.El
.Pp
Only active cooling is currently supported on
.Nx .
.Pp
It should be also noted that the internal
functioning of these cooling policies vary across machines.
On some machines the operating system may have little control over
the thermal zones as the firmware manages the thermal control internally,
whereas on other machines the policies may be exposed to the implementation
at their full extent.
.Sh EVENTS
The
.Nm
driver knows about the active cooling levels, the current
temperatures, and critical, hot, and passive temperature thresholds
(as supported by the hardware).
The driver is able to send events to
.Xr powerd 8
when the sensor's state has changed.
When a Thermal Zone is either critical or
.Dq hot ,
the
.Pa /etc/powerd/scripts/sensor_temperature
script will be invoked with a
.Em critical-over
event.
.Pp
The critical temperature is the threshold for system shutdown.
Depending on the hardware, the mainboard will take down the system
instantly and no event will have a chance to be sent.
.Sh SEE ALSO
.Xr acpi 4 ,
.Xr acpifan 4 ,
.Xr envsys 4 ,
.Xr envstat 8 ,
.Xr powerd 8
.Sh HISTORY
The
.Nm
driver
appeared in
.Nx 2.0 .
.Sh AUTHORS
.An Jared D. McNeill Aq Mt jmcneill@invisible.ca
.Sh CAVEATS
While no pronounced bugs are known to exist,
several caveats can be mentioned:
.Bl -bullet
.It
Passive cooling is not implemented.
.It
There is no user-controllable way to switch between active and passive
cooling, although the specifications support such transforms on some machines.
.It
The
.Dq hot
temperature is a threshold in which the system ought to be put into
.Tn S4
sleep.
This sleep state
.Pq Dq suspend to disk
is not supported on
.Nx .
.El