summaryrefslogtreecommitdiff
path: root/usr.sbin/envstat/envstat.8
diff options
context:
space:
mode:
authorxtraeme <xtraeme@NetBSD.org>2007-07-01 07:39:45 +0000
committerxtraeme <xtraeme@NetBSD.org>2007-07-01 07:39:45 +0000
commitaf211bb4e3c79fdc4e4644b7acb8564151316a4d (patch)
treebc4250211dd14debde531558d27682404fe1b757 /usr.sbin/envstat/envstat.8
parentda3f163bd280223c1d17fd1ff78946be2df177b8 (diff)
Imported envsys 2, a brief description of the new features:
(Part 3: userland) * Support for detachable sensors. * Cleaned up the API for simplicity and efficiency. * Ability to send capacity/critical/warning events to powerd(8). * Adapted all the code to the new locking order. * Compatibility with the old envsys API: the ENVSYS_GTREINFO and ENVSYS_GTREDATA ioctl(2)s are supported. * Added support for a 'dictionary based communication channel' between sysmon_power(9) and powerd(8), that means there is no 32 bytes event size restriction anymore. * Binary compatibility with old envstat(8) and powerd(8) via COMPAT_40. * All drivers with the n^2 gtredata bug were fixed, PR kern/36226. Tested by: blymn: smsc(4). bouyer: ipmi(4), mfi(4). kefren: ug(4). njoly: viaenv(4), adt7463.c. riz: owtemp(4). xtraeme: acpiacad(4), acpibat(4), acpitz(4), aiboost(4), it(4), lm(4).
Diffstat (limited to 'usr.sbin/envstat/envstat.8')
-rw-r--r--usr.sbin/envstat/envstat.8310
1 files changed, 272 insertions, 38 deletions
diff --git a/usr.sbin/envstat/envstat.8 b/usr.sbin/envstat/envstat.8
index 227c66b3549..5bdee4fb66f 100644
--- a/usr.sbin/envstat/envstat.8
+++ b/usr.sbin/envstat/envstat.8
@@ -1,10 +1,10 @@
-.\" $NetBSD: envstat.8,v 1.15 2007/05/07 11:01:28 xtraeme Exp $
+.\" $NetBSD: envstat.8,v 1.16 2007/07/01 07:39:46 xtraeme Exp $
.\"
-.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2000, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
-.\" by Bill Squier.
+.\" by Juan Romero Pardines and Bill Squier.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -34,40 +34,52 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 7, 2007
+.Dd June 15, 2007
.Dt ENVSTAT 8
.Os
.Sh NAME
.Nm envstat
-.Nd display environmental sensor readings
+.Nd utility to handle environmental sensors
.Sh SYNOPSIS
.Nm
-.Op Fl flr
+.Op Fl Dflx
+.Op Fl d Ar device
.Op Fl i Ar interval
-.Op Fl n Ar headrep
+.Op Fl m Ar critical=... critmax=... critmin=... desc=... rfact=...
.Op Fl s Ar sensor1,sensor2,...
.Op Fl w Ar width
-.Op Ar device
.Sh DESCRIPTION
.Nm
-displays sensor readings from any device which supports the
+is a utility that handles various aspects of the sensors
+registered with the
.Xr envsys 4
-API.
-Readings are displayed in columns, one column per sensor.
-Column widths as well as displayed sensors are fully customizable.
-The column headers display the name (stored in the device driver) as
-well as the units of each sensor.
+framework.
+It is capable of displaying sensor values as well as
+changing parameters and setting critical limits for the sensors.
.Pp
-The options are as follows:
+In display mode, column widths as well as displayed sensors
+are fully customizable.
+Critical limits can be set in a per-sensor basis.
+If critical limits were set previously, the display mode will show
+the critical limits in addition to the current values.
+.Pp
+The following options are available:
.Bl -tag -width flag
+.It Fl D
+Display the names of the drivers that were registered with
+the
+.Xr envsys 4
+framework, one per line.
+.It Fl d
+Display only the sensors for a given
+.Ar driver .
+This is useful when there are multiple drivers registered and
+you want to only see those from a specific driver.
.It Fl f
-Display any temperature values in degrees Fahrenheit.
+Display temperature values in degrees Fahrenheit.
The default is to display temperature values in degrees Celsius.
-.It Fl l
-List the names of all supported sensors, one per line.
-Use of this flag causes
-.Nm
-to ignore all other option flags.
+When changing properties on a sensor and this flag is specified,
+the value provided must be in degress Fahrenheit too.
.It Fl i
Repeat the display every
.Ar interval
@@ -78,17 +90,23 @@ See the individual device's manual page for meaningful values for
If not specified, or specified as 0,
.Nm
produces one line of values and exits.
-.It Fl n
-Display a new header every
-.Ar headrep
-lines.
-An argument of 0 disables header line printing completely.
-The default is every 22 lines.
-.It Fl r
-Display the sensors row wise.
-This is useful when the number of sensors is large.
-This option also displays fractional values when present
-(e.g., the percentage battery charge).
+.It Fl l
+List the names of all supported sensors, one per line.
+Use of this flag causes
+.Nm
+to ignore all other option flags.
+.It Fl m
+This flag can be used to change a description of a sensor, to
+change the rfact (resistor factor) in a voltage sensor or
+to set critical capacity for (battery sensors) and critical
+min and max limits (for all supported sensors).
+Recognized keywords are:
+.Ar critical , critmax , critmin , desc ,
+and
+.Ar rfact .
+See the
+.Sx EXAMPLES
+section for more information.
.It Fl s
Restrict the display to the named sensors.
The sensor names must be supplied as a comma separated list.
@@ -98,15 +116,218 @@ Use
.Ar width
as the column width for the output.
Each column is additionally separated by a single space.
-The default is either the length of the longest sensor
-name or spread evenly to fill 80 columns, whichever is greater.
+The default is the length of the longest sensor name.
+.It Fl x
+Shows the property list used by the
+.Xr sysmon_envsys 9
+framework that contains details about all registered drivers
+and sensors.
.El
+.Ss CRITICAL LIMITS
+Starting with
+.Tn envsys 2 ,
+it is possible to set critical limits on a specified sensor.
+Only one critical limit can be set at a time for a sensor.
+For example, you cannot assign multiple limits for the same
+sensor or for different sensors.
+.Pp
+There are three types of
+critical limits:
+.Ar capacity ,
+.Ar max ,
+and
+.Ar min .
+When one of them is set and sensor's current value reaches
+it, an event will be sent to
+.Xr powerd 8 .
+.Pp
+Three arguments are required to set/remove a critical/capacity limit,
+to change a description or to change the rfact:
+.Pp
+.Bl -item -offset indent -compact
+.It
+.Fl d
+is required to specify the device that is handling
+the sensor.
+.It
+.Fl m
+is required to set the new target mode.
+.It
+.Fl s
+is required to specify sensor's name.
+.El
+.Pp
+The available targets for the
+.Fl m
+flag are:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+.Ar critical
+accepts a percentage number for battery sensors (those showing
+a percentage in display mode), also the
+.Sy remove
+keyword can be used to remove the limit.
+.It
+.Ar critmax
+accepts a number that will be used for the max critical limit
+or accepts the
+.Sy remove
+keyword.
+.It
+.Ar critmin
+accepts a number that will be used for the min critical limit
+or accepts the
+.Sy remove
+keyword.
+.It
+.Ar desc
+accepts a new string that will be used as new description.
+.It
+.Ar rfact
+accepts a number that will be used as new rfact in voltage sensors.
+.El
+.Pp
+Also is possible to remove a critical limit if one was set before,
+with the
+.Ar remove
+keyword passed to the
+.Ar critical ,
+.Ar critmax ,
+or
+.Ar critmin
+target.
+See the
+.Sx EXAMPLES
+for information how to use it.
+.Pp
+.Ss CONFIGURATION FILE
+It's possible to change properties with the
+.Pa /etc/envsys.conf
+configuration file. The syntax for this file is the following:
+.Bd -literal
+device:sensor name:target:value
+
+aiboost0:CPU Temperature:critmax:70
+lm0:Temp0:desc:CPU Temperature
+smsc0:+3.3V:rfact:56000
+.Ed
+.Pp
+In the example configuration file the first argument is the name of
+the device, second argument is the name of the sensor that we want to change,
+third argument is the target that will be used for the
+.Ar -m
+flag and finally the four arguments in the value that will be used for the
+target.
+.Pp
+The first example sets a critical over limit of
+.Dq 70
+degC to the
+.Dq CPU Temperature
+sensor in the
+.Dq aiboost0
+device. By default the value specified on temperature sensors must be
+in degrees Celsius but also is possible to specify it in degrees Fahrenheit too.
+The
+.Em value
+argument will have to contain the
+.Dq degF
+keyword:
+.Bd -literal
+aiboost0:CPU Temperature:critmax:120degF
+.Ed
+.Pp
+The second example in the configuration file sets the description
+.Dq CPU Temperature
+to the sensor
+.Dq Temp0
+in the
+.Dq lm0
+device.
+.Pp
+The last example in the configuration file sets the rfact value to
+.Em 56000
+to the
+.Dq +3.3V
+sensor in the
+.Dq smsc0
+device.
+.Pp
+It's possible to set all these properties at boot time with the
+.Xr rc.d 8
+script available at
+.Pa /etc/rc.d/envsys .
+.Pp
.Sh EXAMPLES
Display the
-.Do acpibat0 charge
-.Dc sensor on one line (row format) every ten seconds:
-.Dl envstat -s \*qacpibat0 charge\*q -r -i 10
+.Dq acpibat0 charge
+sensor on one line every ten seconds:
+.Pp
+.Dl $ envstat -s \*qacpibat0 charge\*q -i 10
+.Pp
+Lists the drivers that are currently registered with
+.Xr envsys 4 :
+.Pp
+.Dl $ envstat -D
+.Pp
+Display the sensors of the driver
+.Ar aiboost0 :
+.Pp
+.Dl $ envstat -d aiboost0
+.Pp
+Change the description string for the
+.Dq +3.3V
+sensor to
+.Dq +3.3 Volts
+in the
+.Ar aiboost0
+device:
+.Pp
+.Dl $ envstat -s \*q+3.3V\*q -d aiboost0 -m desc=\*q+3.3 Volts\*q
+.Pp
+Set a critical max limit to 60 degC for the
+.Dq CPU Temp
+sensor, in the
+.Ar aiboost0
+device:
+.Pp
+.Dl $ envstat -s \*qCPU Temp\*q -d aiboost0 -m critmax=60
+.Pp
+Set a critical min limit to 1000 RPMs for the
+.Dq CPU Fan
+sensor, in the
+.Ar aiboost0
+device:
+.Pp
+.Dl $ envstat -s \*qCPU Fan\*q -d aiboost0 -m critmin=1000
+.Pp
+Remove a max critical limit for the
+.Dq CPU Temp
+sensor, in the
+.Ar aiboost0
+device:
+.Pp
+.Dl $ envstat -s \*qCPU Temp\*q -d aiboost0 -m critmax=remove
+.Pp
+Change the resistor factor (rfact) to 56000 for the
+.Dq +3.3V
+sensor, in the
+.Ar lm0
+device:
+.Pp
+.Dl $ envstat -s \*q+3.3V\*q -d lm0 -m rfact=56000
+.Pp
+Set a critical capacity to
+.Sy 10%
+for the
+.Dq acpibat0 charge
+sensor, in the
+.Ar acpibat0
+device:
+.Pp
+.Dl $ envstat -s \*qacpibat0 charge\*q -dacpibat0 -m critical=10
.Sh SEE ALSO
+.Xr proplib 3 ,
.Xr acpiacad 4 ,
.Xr acpibat 4 ,
.Xr acpitz 4 ,
@@ -122,10 +343,23 @@ Display the
.Xr owtemp 4 ,
.Xr sparc/tctrl 4 ,
.Xr sparc64/envctrl 4 ,
+.Xr smsc 4 ,
.Xr tm121temp 4 ,
.Xr ug 4 ,
-.Xr viaenv 4 .
+.Xr viaenv 4
.Sh HISTORY
.Nm
appeared in
.Nx 1.5 .
+It was completely rewritten from scratch for
+.Nx 5.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+utility that appeared in
+.Nx 5.0
+was written by
+.An Juan Romero Pardines .
+The previous version was written by
+.An Bill Squier .