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 distinct 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 sensor type is required. Fixed limits on the number of sensors per type are not desirable.

4.  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.

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 system-internal, and system-external environmental sensors.

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.

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 numbers 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 conceivable 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 multiply 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), adt7467c(4), aiboost(4), ipmi(4), it(4), lm(4), lmtemp(4), nsclpcsio(4), owtemp(4), sparc/tctrl(4), sparc64/envctrl(4), tm121temp(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.