Co-Authored by Bill Squier and Tim Rightnour
|Rev 1.

|Differences between Rev 0 and Rev 1 are marked with a "|" in the left
|margin.


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

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

|ENVSYS_GRANGE (envsys_range_t)
|	The caller fills in the units member of:
|
|	typedef struct envsys_range {
|		u_int low;
|		u_int high;
|
|		u_int units;			/* see GTREDATA */
|	};
|
|	The driver fills in the low and high values such that
|	sensor numbers [low..high] contain sensors of type "units".
|
|	NOTE: high < low implies no sensors of the unit type specified
|	exist.

ENVSYS_GTREDATA (envsys_temp_data_t) /* or rpm, or electrical */

	These commands make use of:

	typedef struct envsys_uint32_data {
		u_int		sensor;

		union {				 /* all data is given	*/
			u_int_32_t	data_us; /* in microKelvins,	*/
			int_32_t	data_s;  /* rpms, volts, amps,	*/
		} cur, min, max, avg;		 /* ohms, watts, etc	*/
						 /* see units below	*/

|		u_int_32_t	warnflags;	 /* warning flags	*/
		u_int_32_t	flags;		 /* see below		*/
		u_int		units;		 /* see below		*/
	} envsys_temp_data_t, envsys_rpm_data_t, envsys_electrical_data_t;

|/* flags for warnflags */
|#define ENVSYS_WARN_OK		0x00000000
|#define ENVSYS_WARN_UNDER	0x00000001
|#define ENVSYS_WARN_CRITUNDER	0x00000002
|#define ENVSYS_WARN_OVER	0x00000004
|#define ENVSYS_WARN_CRITOVER	0x00000008

/* types for units */
#define ENVSYS_STEMP 1
#define ENVSYS_SFANRPM 2
#define ENVSYS_SVOLTS_AC 3
#define ENVSYS_SVOLTS_DC 4
#define ENVSYS_SOHMS 5
#define ENVSYS_SWATTS 6
#define ENVSYS_SAMPS 7

	The driver may return ENVSYS_WARN_OK at all times if the hardware
	or driver does not support warning flags.

|	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  0x00000010
			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_STREINFO (envsys_temp_info_t) /* or rpm, or electrical */

ENVSYS_GTREINFO (envsys_temp_info_t) /* or rpm, or electrical */

	These commands make use of:

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

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

		u_int_32_t	flags;		/* ENVSYS_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.
	
	The sensor number, and units number, tell the driver which sensor
	and type, the user is attempting to program.

	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.

-- 
Bill Squier (groo@cs.stevens-tech.edu)
http://www.cs.stevens-tech.edu/~groo
Ph: (201)216-5486   Fax: (201)216-8249