envsys(4)
- NetBSD Manual Pages
ENVSYS(4) NetBSD Kernel Interfaces Manual ENVSYS(4)
NAME
envsys -- Environmental Systems API
SYNOPSIS
#include <sys/envsys.h>
DESCRIPTION
This API is experimental and may be deprecated at
any time
There are a number of considerations:
1. This API is designed to support various environmental sensor ICs
available on modern motherboards. Initially it supports three dis-
tinct sensor types: fan speed, temperature, and voltage. Additional
sensor types can be added with new ioctl's without disrupting the
current API.
2. 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.
3. The number of registers for each class of sensor varies among
devices. Therefore a way to enumerate all data of a particular sen-
sor type is required. Fixed limits on the number of sensors per
type are not desirable.
4. Some ICs provide useful statistical information. Collecting reli-
able statistical information in userland from a polled device is
problematic. We would like to use the on-chip information when it
is available.
5. 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.
6. The API is designed in a way that can be used to monitor both sys-
tem-internal, and system-external environmental sensors.
For the purposes of this API, all devices must number the sensors sequen-
tially, beginning with 0. Moreover, all sensors of the same type must
occupy a sub-interval of [0..n-1]. This arrangement allows easy itera-
tion over the entire collection of sensors or over sensors of a particu-
lar type.
The following ioctl(2)'s must be supported by any device claiming to be
compliant with version 1.0 of envsys:
ENVSYS_VERSION (int)
Returns API version * 1000. A userland application could use
this command to determine further supported ioctl's of the
device.
ENVSYS_GRANGE (envsys_range_t)
The caller fills in the units member of:
struct envsys_range {
u_int low;
u_int high;
u_int units; /* see GTREDATA */
};
typedef struct envsys_range envsys_range_t;
The driver fills in the low and high values such that sensor num-
bers from low to high, inclusive, contain sensors of type units.
NOTE: high < low implies no sensors of the unit type specified
exist.
ENVSYS_GTREDATA (envsys_tre_data_t)
This command makes use of:
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;
At request time, the caller of this command fills only the sensor
member with the sensor number for which data is being requested.
The structure is returned with available data filled in by the
driver.
Zero or more of the following bits may be set in validflags:
ENVSYS_FVALID
Not set implies an illegal sensor number was
requested.
ENVSYS_FCURVALID
ENVSYS_FMINVALID
ENVSYS_FMAXVALID
ENVSYS_FAVGVALID
ENVSYS_FFRACVALID
Set if these fields are filled with valid data.
Although !ENVSYS_FVALID might be implied from the
absence of all other *VALID flags, it is conceiv-
able that some ICs have a period during which valid
sensors contain invalid data.
Valid warnflags are:
ENVSYS_WARN_OK
ENVSYS_WARN_UNDER
ENVSYS_WARN_CRITUNDER
ENVSYS_WARN_OVER
ENVSYS_WARN_CRITOVER
The driver may return ENVSYS_WARN_OK at all times if the hardware
or driver does not support warning flags.
Valid units are:
ENVSYS_STEMP
ENVSYS_SFANRPM
ENVSYS_SVOLTS_AC
ENVSYS_SVOLTS_DC
ENVSYS_SOHMS
ENVSYS_SWATTS
ENVSYS_SAMPS
ENVSYS_SWATTHOUR
ENVSYS_SAMPHOUR
ENVSYS_INDICATOR
ENVSYS_INTEGER
ENVSYS_NSENSORS
ENVSYS_STREINFO (envsys_basic_info_t)
ENVSYS_GTREINFO (envsys_basic_info_t)
These commands make use of:
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;
ENVSYS_STREINFO is for setting this information in the driver,
while ENVSYS_GTREINFO is for retrieving this information.
To retrieve information, simply fill in the sensor member.
All environmental sensor types read the supplied desc field and
store the contents for subsequent requests. The driver is
expected to supply a default NULL terminated string for desc.
RPM sensor types additionally read the nominal RPM value from
rpms. Voltage sensors read rfact. Drivers are expected to mul-
tiply DC voltage values by this factor before returning them to
the user.
The driver will fill in the validflags value, indicating to the
user that he has successfully programmed or retrieved data from
an existing sensor.
SEE ALSO
acpiacad(4), acpibat(4), acpitz(4), lm(4), it(4), ug(4), viaenv(4),
envstat(8)
BUGS
This entire API should be replaced by a sysctl(8) interface or a kernel
events mechanism, should one be developed.
NetBSD 4.0 January 7, 2006 NetBSD 4.0
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.