.\"	$NetBSD: envsys.4,v 1.16 2004/05/11 22:55:00 wiz Exp $
.\"
.\"
.\" Copyright (c) 2000, 2004 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 April 24, 2004
.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)
This command makes use of:
.Bd -literal
typedef struct envsys_tre_data {
	u_int sensor;
	union {				/* all data is given */
		u_int32_t data_us;	/* in microKelvins, */
		int32_t data_s;		/* rpms, volts, amps, */
	} cur, min, max, avg;		/* ohms, watts, etc */
					/* see units below */

	u_int32_t	warnflags;	/* warning flags */
	u_int32_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 */
	u_int32_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 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.