Can we join this together with SAF-TE (see http://www.safte.org) and SES
(ftp://ftp.t10.org/t10/drafts/ses/ses-r08b.pdf) specifications so that
SCSI based environmental sensors are also part of this?



On Tue, 9 Nov 1999, Tim Rightnour wrote:

> 
> 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/
>