Copyright (c) 2000, 2004, 2006 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Tim Rightnour and Bill Squier
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by the NetBSD
Foundation, Inc. and its contributors.
4. Neither the name of The NetBSD Foundation nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd May 7, 2007 .Dt ENVSYS 4 .Os .Sh NAME .Nm envsys .Nd Environmental Systems API .Sh SYNOPSIS n sys/envsys.h .Sh DESCRIPTION d -unfilled -offset center .Em This API is experimental and may be deprecated at .Em any time .Ed
p There are a number of considerations: l -enum t 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. t 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. t 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 are not desirable. t 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. t 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. t The API is designed in a way that can be used to monitor both system-internal, and system-external environmental sensors. .El
p 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.
p The following .Xr ioctl 2 Ns 's must be supported by any device claiming to be compliant with version 1.0 of .Nm :
p l -tag -width indent t Dv ENVSYS_VERSION (int) Returns API version * 1000. A userland application could use this command to determine further supported ioctl's of the device. t Dv ENVSYS_GRANGE (envsys_range_t) The caller fills in the .Va units member of: d -literal struct envsys_range { u_int low; u_int high; u_int units; /* see GTREDATA */ }; typedef struct envsys_range envsys_range_t; .Ed
p The driver fills in the .Va low and .Va high values such that sensor numbers from .Va low to .Va high , inclusive, contain sensors of type .Va units .
p NOTE: .Va high \*[Lt] .Va low implies no sensors of the unit type specified exist. t Dv ENVSYS_GTREDATA (envsys_tre_data_t) This command makes use of: d -literal typedef struct envsys_tre_data { u_int sensor; union { /* all data is given */ uint32_t data_us; /* in microKelvins, */ int32_t data_s; /* rpms, volts, amps, */ } cur, min, max, avg; /* ohms, watts, etc */ /* see units below */ uint32_t warnflags; /* warning flags */ uint32_t validflags; /* sensor valid flags */ u_int units; /* type of sensor */ } envsys_tre_data_t; .Ed
p At request time, the caller of this command fills only the .Va sensor member with the sensor number for which data is being requested. The structure is returned with available data filled in by the driver.
p Zero or more of the following bits may be set in .Va validflags :
p l -tag -width indent -compact -offset indent t Dv ENVSYS_FVALID Not set implies an illegal sensor number was requested.
p t Dv ENVSYS_FCURVALID t Dv ENVSYS_FMINVALID t Dv ENVSYS_FMAXVALID t Dv ENVSYS_FAVGVALID t Dv ENVSYS_FFRACVALID Set if these fields are filled with valid data.
p Although .Dv !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. .El
p Valid .Va warnflags are:
p l -tag -width indent -compact -offset indent t Dv ENVSYS_WARN_OK t Dv ENVSYS_WARN_UNDER t Dv ENVSYS_WARN_CRITUNDER t Dv ENVSYS_WARN_OVER t Dv ENVSYS_WARN_CRITOVER .El
p The driver may return .Dv ENVSYS_WARN_OK at all times if the hardware or driver does not support warning flags.
p Valid .Va units are:
p l -tag -width indent -compact -offset indent t Dv ENVSYS_STEMP t Dv ENVSYS_SFANRPM t Dv ENVSYS_SVOLTS_AC t Dv ENVSYS_SVOLTS_DC t Dv ENVSYS_SOHMS t Dv ENVSYS_SWATTS t Dv ENVSYS_SAMPS t Dv ENVSYS_SWATTHOUR t Dv ENVSYS_SAMPHOUR t Dv ENVSYS_INDICATOR t Dv ENVSYS_INTEGER t Dv ENVSYS_NSENSORS .El t Dv ENVSYS_STREINFO (envsys_basic_info_t) t Dv ENVSYS_GTREINFO (envsys_basic_info_t) These commands make use of: d -literal typedef struct envsys_basic_info { u_int sensor; /* sensor number */ u_int units; /* type of sensor */ char desc[33]; /* sensor description */ u_int rfact; /* for volts, (int)(factor x 10^4) */ u_int rpms; /* for fans */ uint32_t validflags; /* sensor valid flags */ } envsys_basic_info_t; .Ed
p .Dv ENVSYS_STREINFO is for setting this information in the driver, while .Dv ENVSYS_GTREINFO is for retrieving this information.
p To retrieve information, simply fill in the .Va sensor member.
p All environmental sensor types read the supplied .Va desc field and store the contents for subsequent requests. The driver is expected to supply a default .Dv NULL terminated string for .Va desc .
p RPM sensor types additionally read the nominal RPM value from .Va rpms . Voltage sensors read .Va rfact . Drivers are expected to multiply DC voltage values by this factor before returning them to the user.
p The driver will fill in the .Va validflags value, indicating to the user that he has successfully programmed or retrieved data from an existing sensor. .El .Sh SEE ALSO .Xr acpiacad 4 , .Xr acpibat 4 , .Xr acpitz 4 , .Xr adt7467c 4 , .Xr aiboost 4 , .Xr ipmi 4 , .Xr it 4 , .Xr lm 4 , .Xr lmtemp 4 , .Xr mfi 4 , .Xr nsclpcsio 4 , .Xr owtemp 4 , .Xr sparc/tctrl 4 , .Xr sparc64/envctrl 4 , .Xr tm121temp 4 , .Xr ug 4 , .Xr viaenv 4 , .Xr envstat 8 .Sh BUGS This entire API should be replaced by a .Xr sysctl 8 interface or a kernel events mechanism, should one be developed.
Indexes created Wed Oct 15 16:09:53 GMT 2025