282 lines
8.1 KiB
Groff
282 lines
8.1 KiB
Groff
.\" $NetBSD: envsys.4,v 1.19 2006/05/13 09:04:48 xtraeme Exp $
|
|
.\"
|
|
.\"
|
|
.\" Copyright (c) 2000, 2004, 2006 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Tim Rightnour and Bill Squier
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 May 13, 2006
|
|
.Dt ENVSYS 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm envsys
|
|
.Nd Environmental Systems API
|
|
.Sh SYNOPSIS
|
|
.In sys/envsys.h
|
|
.Sh DESCRIPTION
|
|
.Bd -unfilled -offset center
|
|
.Em This API is experimental and may be deprecated at
|
|
.Em any time
|
|
.Ed
|
|
.Pp
|
|
There are a number of considerations:
|
|
.Bl -enum
|
|
.It
|
|
This API is designed to support various environmental sensor ICs
|
|
available on modern motherboards.
|
|
Initially it supports three
|
|
distinct sensor types: fan speed, temperature, and voltage.
|
|
Additional sensor types can be added with new ioctl's without
|
|
disrupting the current API.
|
|
.It
|
|
Many sensor ICs have no fixed assignment of registers to
|
|
physical phenomena.
|
|
Thus, some userland mechanism of
|
|
assigning meanings to the registers is required to allow
|
|
userland utilities to produce reasonable output.
|
|
.It
|
|
The number of registers for each class of sensor varies
|
|
among devices.
|
|
Therefore a way to enumerate all data of
|
|
a particular sensor type is required.
|
|
Fixed limits on the
|
|
number of sensors per type are not desirable.
|
|
.It
|
|
Some ICs provide useful statistical information.
|
|
Collecting reliable statistical information in userland
|
|
from a polled device is problematic.
|
|
We would like to use
|
|
the on-chip information when it is available.
|
|
.It
|
|
A useful balance between complexity of use and amount
|
|
of available information is desired.
|
|
While it may be
|
|
possible to allow for an unlimited number of statistical
|
|
measures to be returned by a device, we have chosen only
|
|
four common ones: current, minimum, maximum, and average.
|
|
Even with this limited set, it may be impractical or
|
|
impossible for devices to produce them all.
|
|
Thus, a
|
|
mechanism to determine which statistics are valid is required.
|
|
.It
|
|
The API is designed in a way that can be used to monitor
|
|
both system-internal, and system-external environmental
|
|
sensors.
|
|
.El
|
|
.Pp
|
|
For the purposes of this API, all devices must number the sensors
|
|
sequentially, beginning with 0.
|
|
Moreover, all sensors of the same
|
|
type must occupy a sub-interval of [0..n-1].
|
|
This arrangement
|
|
allows easy iteration over the entire collection of sensors or over
|
|
sensors of a particular type.
|
|
.Pp
|
|
The following
|
|
.Xr ioctl 2 Ns 's
|
|
must be supported by any device claiming to
|
|
be compliant with version 1.0 of
|
|
.Nm :
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Dv ENVSYS_VERSION (int)
|
|
Returns API version * 1000.
|
|
A userland application could use
|
|
this command to determine further supported ioctl's of the
|
|
device.
|
|
.It Dv ENVSYS_GRANGE (envsys_range_t)
|
|
The caller fills in the
|
|
.Va units
|
|
member of:
|
|
.Bd -literal
|
|
struct envsys_range {
|
|
u_int low;
|
|
u_int high;
|
|
u_int units; /* see GTREDATA */
|
|
};
|
|
typedef struct envsys_range envsys_range_t;
|
|
.Ed
|
|
.Pp
|
|
The driver fills in the
|
|
.Va low
|
|
and
|
|
.Va high
|
|
values such that
|
|
sensor numbers from
|
|
.Va low
|
|
to
|
|
.Va high ,
|
|
inclusive, contain sensors of type
|
|
.Va units .
|
|
.Pp
|
|
NOTE:
|
|
.Va high
|
|
\*[Lt]
|
|
.Va low
|
|
implies no sensors of the unit type specified exist.
|
|
.It Dv ENVSYS_GTREDATA (envsys_tre_data_t)
|
|
This command makes use of:
|
|
.Bd -literal
|
|
typedef struct envsys_tre_data {
|
|
u_int sensor;
|
|
union { /* all data is given */
|
|
uint32_t data_us; /* in microKelvins, */
|
|
int32_t data_s; /* rpms, volts, amps, */
|
|
} cur, min, max, avg; /* ohms, watts, etc */
|
|
/* see units below */
|
|
|
|
uint32_t warnflags; /* warning flags */
|
|
uint32_t validflags; /* sensor valid flags */
|
|
u_int units; /* type of sensor */
|
|
} envsys_tre_data_t;
|
|
.Ed
|
|
.Pp
|
|
At request time, the caller of this command fills only the
|
|
.Va sensor
|
|
member with the sensor number for which data is being
|
|
requested.
|
|
The structure is returned with available data
|
|
filled in by the driver.
|
|
.Pp
|
|
Zero or more of the following bits may be set in
|
|
.Va validflags :
|
|
.Pp
|
|
.Bl -tag -width indent -compact -offset indent
|
|
.It Dv ENVSYS_FVALID
|
|
Not set implies an illegal sensor number was requested.
|
|
.Pp
|
|
.It Dv ENVSYS_FCURVALID
|
|
.It Dv ENVSYS_FMINVALID
|
|
.It Dv ENVSYS_FMAXVALID
|
|
.It Dv ENVSYS_FAVGVALID
|
|
.It Dv ENVSYS_FFRACVALID
|
|
Set if these fields are filled with valid data.
|
|
.Pp
|
|
Although
|
|
.Dv !ENVSYS_FVALID
|
|
might be implied from the absence of
|
|
all other *VALID flags, it is conceivable that some ICs have
|
|
a period during which valid sensors contain invalid data.
|
|
.El
|
|
.Pp
|
|
Valid
|
|
.Va warnflags
|
|
are:
|
|
.Pp
|
|
.Bl -tag -width indent -compact -offset indent
|
|
.It Dv ENVSYS_WARN_OK
|
|
.It Dv ENVSYS_WARN_UNDER
|
|
.It Dv ENVSYS_WARN_CRITUNDER
|
|
.It Dv ENVSYS_WARN_OVER
|
|
.It Dv ENVSYS_WARN_CRITOVER
|
|
.El
|
|
.Pp
|
|
The driver may return
|
|
.Dv ENVSYS_WARN_OK
|
|
at all times if the hardware or driver does not support warning flags.
|
|
.Pp
|
|
Valid
|
|
.Va units
|
|
are:
|
|
.Pp
|
|
.Bl -tag -width indent -compact -offset indent
|
|
.It Dv ENVSYS_STEMP
|
|
.It Dv ENVSYS_SFANRPM
|
|
.It Dv ENVSYS_SVOLTS_AC
|
|
.It Dv ENVSYS_SVOLTS_DC
|
|
.It Dv ENVSYS_SOHMS
|
|
.It Dv ENVSYS_SWATTS
|
|
.It Dv ENVSYS_SAMPS
|
|
.It Dv ENVSYS_SWATTHOUR
|
|
.It Dv ENVSYS_SAMPHOUR
|
|
.It Dv ENVSYS_INDICATOR
|
|
.It Dv ENVSYS_INTEGER
|
|
.It Dv ENVSYS_NSENSORS
|
|
.El
|
|
.It Dv ENVSYS_STREINFO (envsys_basic_info_t)
|
|
.It Dv ENVSYS_GTREINFO (envsys_basic_info_t)
|
|
These commands make use of:
|
|
.Bd -literal
|
|
typedef struct envsys_basic_info {
|
|
u_int sensor; /* sensor number */
|
|
u_int units; /* type of sensor */
|
|
char desc[33]; /* sensor description */
|
|
u_int rfact; /* for volts, (int)(factor x 10^4) */
|
|
u_int rpms; /* for fans */
|
|
uint32_t validflags; /* sensor valid flags */
|
|
} envsys_basic_info_t;
|
|
.Ed
|
|
.Pp
|
|
.Dv ENVSYS_STREINFO
|
|
is for setting this information in the driver,
|
|
while
|
|
.Dv ENVSYS_GTREINFO
|
|
is for retrieving this information.
|
|
.Pp
|
|
To retrieve information, simply fill in the
|
|
.Va sensor
|
|
member.
|
|
.Pp
|
|
All environmental sensor types read the supplied
|
|
.Va desc
|
|
field and store the contents for subsequent requests.
|
|
The driver is expected to supply a default
|
|
.Dv NULL
|
|
terminated string for
|
|
.Va desc .
|
|
.Pp
|
|
RPM sensor types additionally read the nominal RPM value from
|
|
.Va rpms .
|
|
Voltage sensors read
|
|
.Va rfact .
|
|
Drivers are expected to multiply DC voltage values by this factor before
|
|
returning them to the user.
|
|
.Pp
|
|
The driver will fill in the
|
|
.Va validflags
|
|
value, indicating to the user that he has successfully programmed or
|
|
retrieved data from an existing sensor.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr acpiacad 4 ,
|
|
.Xr acpibat 4 ,
|
|
.Xr acpitz 4 ,
|
|
.Xr lm 4 ,
|
|
.Xr it 4 ,
|
|
.Xr viaenv 4 ,
|
|
.Xr envstat 8
|
|
.Sh BUGS
|
|
This entire API should be replaced by a
|
|
.Xr sysctl 8
|
|
interface or a kernel events mechanism, should one be developed.
|