Co-Authored by Bill Squier and Tim Rightnour

------
The following API is presented with the caveat that polling devices of 
this type is not a good idea.  The proper solution is use some form of 
"kernel events" mechanism.

ENVSYS API 1.0
--------------


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

The following ioctl(2)'s must be supported by any device claiming to
be compliant with version 1.0 of the ENVSYS API.

For the purposes of this API, all devices must number the sensors of
each type sequentially, beginning with 0.  Thus if there are n
temperature sensors, they *must* be numbered 0..n-1.

ENVSYS_VERSION (int)
        Returns API version * 1000.  A userland application could use
        this ioctl to determine further supported ioctl's of the
        device.

ENVSYS_GTEMPDATA (envsys_temp_data_t)
ENVSYS_GRPMDATA  (envsys_rpm_data_t)
ENVSYS_GELECDATA (envsys_electrical_data_t)

        These commands make use of:

        typedef struct envsys_uint32_data {
                u_int           sensor;

                u_int_32_t      cur;            /* all data in given  */
                u_int_32_t      min;            /* in microKelvins or */
                u_int_32_t      max;            /* rpms               */
                u_int_32_t      avg;

                u_int_32_t      flags;          /* see below          */
        } envsys_temp_data_t, envsys_rpm_data_t;


        typedef struct envsys_int32_data {
                u_int           sensor;

                int_32_t        cur;            /* all data in given  */
                int_32_t        min;            /* in microvolts, ohms */
                int_32_t        max;            /* watts, microamps */
                int_32_t        avg;            /* depending on units */

                u_int_32_t      flags;          /* see below          */
                u_int           units;          /* see below */
        } envsys_electrical_data_t;

#define ENVSYS_EVOLTS_AC 1
#define ENVSYS_EVOLTS_DC 2
#define ENVSYS_EOHMS 3
#define ENVSYS_EWATTS 4
#define ENVSYS_EAMPS 5

        At request time, the caller of this command fills 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.

        Flags are:

                ENVSYS_FVALID  0x00000001
                        Not set implies an illegal sensor number was
                        requested.

                ENVSYS_FCURVALID  0x00000002
                ENVSYS_FMINVALID  0x00000004
                ENVSYS_FMAXVALID  0x00000008
                ENVSYS_FAVGVALID  0x00000016
                        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.

        
ENVSYS_STEMPINFO (envsys_temp_info_t)
ENVSYS_SRPMINFO  (envsys_rpm_info_t)
ENVSYS_SVOLTINFO (envsys_electrical_info_t)

ENVSYS_GTEMPINFO (envsys_temp_info_t)
ENVSYS_GRPMINFO  (envsys_rpm_info_t)
ENVSYS_GVOLTINFO (envsys_electrical_info_t)

        These commands make use of:

        typedef struct envsys_basic_info {
                u_int           sensor;
                wchar_t         desc[33];       /* description  */

                u_int           rpms;           /* for fans, set
                                                   nominal rpms */

                u_int_32_t      flags;          /* SENSOR_FVALID */
        } envsys_temp_info_t, envsys_rpm_info_t, envsys_electrical_info_t;

        The "S" series is for setting this information in the driver,
        the "G" series is for retrieving this information.
        
        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.

        The driver will fill in the flags value, indicating to the user
        that he has successfully programmed an existing sensor.

DRIVER IMPLEMENTATION NOTES

        The driver is expected to allow multiple open instances of the
        device, and serialize requests if neccesary internally.  For the
        purposes of this API, only open, close and ioctl entrypoints need
        exist.  Additional entrypoints, or ioctls for programming IC
        specific features such as watchpoints are outside the scope of
        this API, and should be designed in a non-interfering manner.
        The driver is not required to provide up-to-date information
        at all times, and may substitute stale data at the discretion
        of the implementor where a read might be too expensive.


---
Tim Rightnour <root@garbled.net>
NetBSD: Free multi-architecture OS http://www.netbsd.org/
NetBSD Mailing lists on the web: http://mail-index.netbsd.org/