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) This command makes use of: 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; 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 */ u_int32_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), 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 3.1.1 April 24, 2004 NetBSD 3.1.1
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.