1.\" $NetBSD: envsys.4,v 1.10 2002/02/13 08:17:34 ross Exp $ 2.\" 3.\" 4.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Tim Rightnour and Bill Squier 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd February 26, 2000 39.Dt ENVSYS 4 40.Os 41.Sh NAME 42.Nm envsys 43.Nd Environmental Systems API 44.Sh SYNOPSIS 45.Fd #include \*[Lt]sys/envsys.h\*[Gt] 46.Sh DESCRIPTION 47.Bd -offset center 48.Em This API is experimental and may be deprecated at 49.Em any time 50.Ed 51.Pp 52There are a number of considerations: 53.Bl -enum 54.It 55This API is designed to support various environmental sensor ICs 56available on modern motherboards. Initially it supports three 57distinct sensor types; fan speed, temperature, and voltage. 58Additional sensor types can be added with new ioctl's without 59disrupting the current API. 60.It 61Many sensor ICs have no fixed assignment of registers to 62physical phenomena. Thus, some userland mechanism of 63assigning meanings to the registers is required to allow 64userland utilities to produce reasonable output. 65.It 66The number of registers for each class of sensor varies 67among devices. Therefore a way to enumerate all data of 68a particular sensor type is required. Fixed limits on the 69number of sensors per type is not desirable. 70.It 71Some ICs provide useful statistical information. 72Collecting reliable statistical information in userland 73from a polled device is problematic. We would like to use 74the on-chip information when it is available. 75.It 76A useful balance between complexity of use and amount 77of available information is desired. While it may be 78possible to allow for an unlimited number of statistical 79measures to be returned by a device, we have chosen only 80four common ones: current, minimum, maximum, and average. 81Even with this limited set, it may be impractical or 82impossible for devices to produce them all. Thus, a 83mechanism to determine which statistics are valid is required. 84.It 85The API is designed in a way that can be used to monitor 86both system-internal, and system-external environmental 87sensors. 88.El 89.Pp 90For the purposes of this API, all devices must number the sensors 91sequentially, beginning with 0. Moreover, all sensors of the same 92type must occupy a sub-interval of [0..n-1]. This arrangement 93allows easy iteration over the entire collection of sensors or over 94sensors of a particular type. 95.Pp 96The following 97.Xr ioctl 2 's 98must be supported by any device claiming to 99be compliant with version 1.0 of 100.Nm 101.Pp 102.Bl -tag -width indent 103.It Dv ENVSYS_VERSION (int) 104Returns API version * 1000. A userland application could use 105this command to determine further supported ioctl's of the 106device. 107.It Dv ENVSYS_GRANGE (envsys_range_t) 108The caller fills in the 109.Va units 110member of: 111.Bd -literal 112typedef struct envsys_range { 113 u_int low; 114 u_int high; 115 116 u_int units; /* see GTREDATA */ 117} envsys_range_t; 118.Ed 119.Pp 120The driver fills in the 121.Va low 122and 123.Va high 124values such that 125sensor numbers from 126.Va low 127to 128.Va high , 129inclusive, contain sensors of type 130.Va units . 131.Pp 132NOTE: 133.Va high 134\*[Lt] 135.Va low 136implies no sensors of the unit type specified exist. 137.It Dv ENVSYS_GTREDATA (envsys_tre_data) 138This command makes use of: 139.Bd -literal 140typedef struct envsys_tre_data { 141 u_int sensor; 142 union { /* all data is given */ 143 u_int32_t data_us; /* in microKelvins, */ 144 int32_t data_s; /* rpms, volts, amps, */ 145 } cur, min, max, avg; /* ohms, watts, etc */ 146 /* see units below */ 147 148 u_int32_t warnflags; /* warning flags */ 149 u_int32_t validflags; /* sensor valid flags */ 150 u_int units; /* type of sensor */ 151} envsys_tre_data_t; 152.Ed 153.Pp 154At request time, the caller of this command fills only the 155.Va sensor 156member with the sensor number for which data is being 157requested. The structure is returned with available data 158filled in by the driver. 159.Pp 160Zero or more of the following bits may be set in 161.Va validflags : 162.Pp 163.Bl -tag -width indent -compact -offset indent 164.It Dv ENVSYS_FVALID 165Not set implies an illegal sensor number was requested. 166.Pp 167.It Dv ENVSYS_FCURVALID 168.It Dv ENVSYS_FMINVALID 169.It Dv ENVSYS_FMAXVALID 170.It Dv ENVSYS_FAVGVALID 171Set if these fields are filled with valid data 172.Pp 173Although 174.Dv !ENVSYS_FVALID 175might be implied from the absence of 176all other *VALID flags, it is conceivable that some ICs have 177a period during which valid sensors contain invalid data. 178.El 179.Pp 180Valid 181.Va warnflags 182are: 183.Pp 184.Bl -tag -width indent -compact -offset indent 185.It Dv ENVSYS_WARN_OK 186.It Dv ENVSYS_WARN_UNDER 187.It Dv ENVSYS_WARN_CRITUNDER 188.It Dv ENVSYS_WARN_OVER 189.It Dv ENVSYS_WARN_CRITOVER 190.El 191.Pp 192The driver may return 193.Dv ENVSYS_WARN_OK 194at all times if the hardware or driver does not support warning flags. 195.Pp 196Valid 197.Va units 198are: 199.Pp 200.Bl -tag -width indent -compact -offset indent 201.It Dv ENVSYS_STEMP 202.It Dv ENVSYS_SFANRPM 203.It Dv ENVSYS_SVOLTS_AC 204.It Dv ENVSYS_SVOLTS_DC 205.It Dv ENVSYS_SOHMS 206.It Dv ENVSYS_SWATTS 207.It Dv ENVSYS_SAMPS 208.El 209.It Dv ENVSYS_STREINFO (envsys_basic_info_t) 210.It Dv ENVSYS_GTREINFO (envsys_basic_info_t) 211These commands make use of: 212.Bd -literal 213typedef struct envsys_basic_info { 214 u_int sensor; /* sensor number */ 215 u_int units; /* type of sensor */ 216 char desc[33]; /* sensor description */ 217 u_int rpms; /* for fans */ 218 u_int rfact; /* for volts, (factor x 10^4) */ 219 u_int32_t validflags; /* sensor valid flags */ 220} envsys_basic_info_t; 221.Ed 222.Pp 223.Dv ENVSYS_STREINFO 224is for setting this information in the driver, 225while 226.Dv ENVSYS_GTREINFO 227is for retrieving this information. 228.Pp 229To retrieve information, simply fill in the 230.Va sensor 231member. 232.Pp 233All environmental sensor types read the supplied 234.Va desc 235field and store the contents for subsequent requests. The 236driver is expected to supply a default 237.Dv NULL 238terminated string for 239.Va desc . 240.Pp 241RPM sensor types additionally read the nominal RPM value from 242.Va rpms . 243Voltage sensors read 244.Va rfact . 245Drivers are expected to multiply DC voltage values by this factor before 246returning them to the user. 247.Pp 248The driver will fill in the 249.Va flags 250value, indicating to the user that he has successfully programmed or 251retrieved data from an existing sensor. 252.El 253.Sh SEE ALSO 254.Xr lm 4 , 255.Xr viaenv 4 , 256.Xr envstat 8 257.Sh BUGS 258This entire API should be replaced by a 259.Xr sysctl 8 260interface or a kernel events mechanism, should one be developed. 261