[src/trunk]: src/share/man/man4 Update this.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/dd8c6f8eb59e
branches:  trunk
changeset: 754254:dd8c6f8eb59e
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Sun Apr 25 06:04:59 2010 +0000

description:
Update this.

Remove the nonsense about passive cooling. As there is no known bugs, speak
about CAVEATS instead, and add few items to this section as a TODO.

diffstat:

 share/man/man4/acpitz.4 |  71 ++++++++++++++++++++++++++++++++++++------------
 1 files changed, 53 insertions(+), 18 deletions(-)

diffs (113 lines):

diff -r 83a5fd92bf11 -r dd8c6f8eb59e share/man/man4/acpitz.4
--- a/share/man/man4/acpitz.4   Sun Apr 25 00:57:12 2010 +0000
+++ b/share/man/man4/acpitz.4   Sun Apr 25 06:04:59 2010 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: acpitz.4,v 1.9 2008/11/09 14:00:48 pgoyette Exp $
+.\" $NetBSD: acpitz.4,v 1.10 2010/04/25 06:04:59 jruoho Exp $
 .\"
 .\" Copyright (c) 2003, 2004 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 9, 2008
+.Dd April 25, 2010
 .Dt ACPITZ 4
 .Os
 .Sh NAME
@@ -35,13 +35,36 @@
 .Sh DESCRIPTION
 The
 .Nm
-driver supports ACPI Thermal Zones.
-.Pp
+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 .
 .Sh EVENTS
 The
 .Nm
@@ -51,23 +74,17 @@
 The driver is able to send events to
 .Xr powerd 8
 when the sensor's state has changed.
-When a Thermal Zone is critical, a
+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 will be sent or if the Thermal Zone is hot, a
-.Em warning-over
-event will be sent to the
-.Pa /etc/powerd/scripts/sensor_temperature
-script.
+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.
-.\" The hot temperature is the temperature threshold for S4 sleep.
-.\" S4 is only supported on small subset of machines and is not known to work.
-The passive temperature is the passive cooling temperature threshold.
-Passive cooling means the Thermal Zone hardware
-doesn't have any software control.
-On capable hardware, active cooling can power on and off fans, for example.
 .Sh SEE ALSO
 .Xr acpi 4 ,
 .Xr envsys 4 ,
@@ -79,5 +96,23 @@
 driver
 appeared in
 .Nx 2.0 .
-.Sh BUGS
-Any policy control such as fan control is not implemented.
+.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