1.\" $NetBSD: envsys.4,v 1.16 2004/05/11 22:55:00 wiz Exp $ 2.\" 3.\" 4.\" Copyright (c) 2000, 2004 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 April 24, 2004 39.Dt ENVSYS 4 40.Os 41.Sh NAME 42.Nm envsys 43.Nd Environmental Systems API 44.Sh SYNOPSIS 45.In sys/envsys.h 46.Sh DESCRIPTION 47.Bd -unfilled -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. 57Initially it supports three 58distinct sensor types: fan speed, temperature, and voltage. 59Additional sensor types can be added with new ioctl's without 60disrupting the current API. 61.It 62Many sensor ICs have no fixed assignment of registers to 63physical phenomena. 64Thus, some userland mechanism of 65assigning meanings to the registers is required to allow 66userland utilities to produce reasonable output. 67.It 68The number of registers for each class of sensor varies 69among devices. 70Therefore a way to enumerate all data of 71a particular sensor type is required. 72Fixed limits on the 73number of sensors per type are not desirable. 74.It 75Some ICs provide useful statistical information. 76Collecting reliable statistical information in userland 77from a polled device is problematic. 78We would like to use 79the on-chip information when it is available. 80.It 81A useful balance between complexity of use and amount 82of available information is desired. 83While it may be 84possible to allow for an unlimited number of statistical 85measures to be returned by a device, we have chosen only 86four common ones: current, minimum, maximum, and average. 87Even with this limited set, it may be impractical or 88impossible for devices to produce them all. 89Thus, a 90mechanism to determine which statistics are valid is required. 91.It 92The API is designed in a way that can be used to monitor 93both system-internal, and system-external environmental 94sensors. 95.El 96.Pp 97For the purposes of this API, all devices must number the sensors 98sequentially, beginning with 0. 99Moreover, all sensors of the same 100type must occupy a sub-interval of [0..n-1]. 101This arrangement 102allows easy iteration over the entire collection of sensors or over 103sensors of a particular type. 104.Pp 105The following 106.Xr ioctl 2 Ns 's 107must be supported by any device claiming to 108be compliant with version 1.0 of 109.Nm : 110.Pp 111.Bl -tag -width indent 112.It Dv ENVSYS_VERSION (int) 113Returns API version * 1000. 114A userland application could use 115this command to determine further supported ioctl's of the 116device. 117.It Dv ENVSYS_GRANGE (envsys_range_t) 118The caller fills in the 119.Va units 120member of: 121.Bd -literal 122struct envsys_range { 123 u_int low; 124 u_int high; 125 u_int units; /* see GTREDATA */ 126}; 127typedef struct envsys_range envsys_range_t; 128.Ed 129.Pp 130The driver fills in the 131.Va low 132and 133.Va high 134values such that 135sensor numbers from 136.Va low 137to 138.Va high , 139inclusive, contain sensors of type 140.Va units . 141.Pp 142NOTE: 143.Va high 144\*[Lt] 145.Va low 146implies no sensors of the unit type specified exist. 147.It Dv ENVSYS_GTREDATA (envsys_tre_data) 148This command makes use of: 149.Bd -literal 150typedef struct envsys_tre_data { 151 u_int sensor; 152 union { /* all data is given */ 153 u_int32_t data_us; /* in microKelvins, */ 154 int32_t data_s; /* rpms, volts, amps, */ 155 } cur, min, max, avg; /* ohms, watts, etc */ 156 /* see units below */ 157 158 u_int32_t warnflags; /* warning flags */ 159 u_int32_t validflags; /* sensor valid flags */ 160 u_int units; /* type of sensor */ 161} envsys_tre_data_t; 162.Ed 163.Pp 164At request time, the caller of this command fills only the 165.Va sensor 166member with the sensor number for which data is being 167requested. 168The structure is returned with available data 169filled in by the driver. 170.Pp 171Zero or more of the following bits may be set in 172.Va validflags : 173.Pp 174.Bl -tag -width indent -compact -offset indent 175.It Dv ENVSYS_FVALID 176Not set implies an illegal sensor number was requested. 177.Pp 178.It Dv ENVSYS_FCURVALID 179.It Dv ENVSYS_FMINVALID 180.It Dv ENVSYS_FMAXVALID 181.It Dv ENVSYS_FAVGVALID 182.It Dv ENVSYS_FFRACVALID 183Set if these fields are filled with valid data. 184.Pp 185Although 186.Dv !ENVSYS_FVALID 187might be implied from the absence of 188all other *VALID flags, it is conceivable that some ICs have 189a period during which valid sensors contain invalid data. 190.El 191.Pp 192Valid 193.Va warnflags 194are: 195.Pp 196.Bl -tag -width indent -compact -offset indent 197.It Dv ENVSYS_WARN_OK 198.It Dv ENVSYS_WARN_UNDER 199.It Dv ENVSYS_WARN_CRITUNDER 200.It Dv ENVSYS_WARN_OVER 201.It Dv ENVSYS_WARN_CRITOVER 202.El 203.Pp 204The driver may return 205.Dv ENVSYS_WARN_OK 206at all times if the hardware or driver does not support warning flags. 207.Pp 208Valid 209.Va units 210are: 211.Pp 212.Bl -tag -width indent -compact -offset indent 213.It Dv ENVSYS_STEMP 214.It Dv ENVSYS_SFANRPM 215.It Dv ENVSYS_SVOLTS_AC 216.It Dv ENVSYS_SVOLTS_DC 217.It Dv ENVSYS_SOHMS 218.It Dv ENVSYS_SWATTS 219.It Dv ENVSYS_SAMPS 220.It Dv ENVSYS_SWATTHOUR 221.It Dv ENVSYS_SAMPHOUR 222.It Dv ENVSYS_INDICATOR 223.It Dv ENVSYS_INTEGER 224.It Dv ENVSYS_NSENSORS 225.El 226.It Dv ENVSYS_STREINFO (envsys_basic_info_t) 227.It Dv ENVSYS_GTREINFO (envsys_basic_info_t) 228These commands make use of: 229.Bd -literal 230typedef struct envsys_basic_info { 231 u_int sensor; /* sensor number */ 232 u_int units; /* type of sensor */ 233 char desc[33]; /* sensor description */ 234 u_int rfact; /* for volts, (int)(factor x 10^4) */ 235 u_int rpms; /* for fans */ 236 u_int32_t validflags; /* sensor valid flags */ 237} envsys_basic_info_t; 238.Ed 239.Pp 240.Dv ENVSYS_STREINFO 241is for setting this information in the driver, 242while 243.Dv ENVSYS_GTREINFO 244is for retrieving this information. 245.Pp 246To retrieve information, simply fill in the 247.Va sensor 248member. 249.Pp 250All environmental sensor types read the supplied 251.Va desc 252field and store the contents for subsequent requests. 253The driver is expected to supply a default 254.Dv NULL 255terminated string for 256.Va desc . 257.Pp 258RPM sensor types additionally read the nominal RPM value from 259.Va rpms . 260Voltage sensors read 261.Va rfact . 262Drivers are expected to multiply DC voltage values by this factor before 263returning them to the user. 264.Pp 265The driver will fill in the 266.Va validflags 267value, indicating to the user that he has successfully programmed or 268retrieved data from an existing sensor. 269.El 270.Sh SEE ALSO 271.Xr acpiacad 4 , 272.Xr acpibat 4 , 273.Xr acpitz 4 , 274.Xr lm 4 , 275.Xr viaenv 4 , 276.Xr envstat 8 277.Sh BUGS 278This entire API should be replaced by a 279.Xr sysctl 8 280interface or a kernel events mechanism, should one be developed. 281