08d5afa292
(Part 4: documentation and configuration files) * Support for detachable sensors. * Cleaned up the API for simplicity and efficiency. * Ability to send capacity/critical/warning events to powerd(8). * Adapted all the code to the new locking order. * Compatibility with the old envsys API: the ENVSYS_GTREINFO and ENVSYS_GTREDATA ioctl(2)s are supported. * Added support for a 'dictionary based communication channel' between sysmon_power(9) and powerd(8), that means there is no 32 bytes event size restriction anymore. * Binary compatibility with old envstat(8) and powerd(8) via COMPAT_40. * All drivers with the n^2 gtredata bug were fixed, PR kern/36226. Tested by: blymn: smsc(4). bouyer: ipmi(4), mfi(4). kefren: ug(4). njoly: viaenv(4), adt7463.c. riz: owtemp(4). xtraeme: acpiacad(4), acpibat(4), acpitz(4), aiboost(4), it(4), lm(4).
409 lines
11 KiB
Groff
409 lines
11 KiB
Groff
.\" $NetBSD: envsys.4,v 1.28 2007/07/01 07:55:51 xtraeme Exp $
|
|
.\"
|
|
.\"
|
|
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Juan Romero Pardines.
|
|
.\"
|
|
.\" 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 June 22, 2007
|
|
.Dt ENVSYS 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm envsys
|
|
.Nd Environmental Systems framework (version 2)
|
|
.Sh SYNOPSIS
|
|
.In sys/envsys.h
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
The
|
|
.Nm
|
|
framework provides support to handle hardware monitor sensors.
|
|
Hardware monitoring chips are able to report values from different types of
|
|
sensors.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
framework consists of two parts:
|
|
.Pp
|
|
.Bl -enum -offset indent -compact
|
|
.It
|
|
the userland part, to receive the current sensor data and
|
|
to set some properties on sensors:
|
|
.Xr envsys 4 .
|
|
.It
|
|
the kernel part that is able to talk to the drivers providing sensor
|
|
data:
|
|
.Xr sysmon_envsys 9 .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
framework uses
|
|
.Xr proplib 3
|
|
for communication between kernel and user space. The following
|
|
.Xr ioctl 2
|
|
types are available:
|
|
.Pp
|
|
.Bl -tag -width XX -compact
|
|
.It Dv ENVSYS_GETDICTIONARY (prop_dictionary_t)
|
|
.Pp
|
|
This
|
|
.Xr ioctl 2
|
|
is used to receive the global dictionary that is being used in
|
|
the kernel by the
|
|
.Xr sysmon_envsys 9
|
|
framework. It will contain an array of dictionaries per device
|
|
and one dictionary per sensor, each of them with its own
|
|
characteristics and values.
|
|
.Pp
|
|
The following XML property list represents a virtual device
|
|
.Dq device0
|
|
with one sensor
|
|
.Dq sensor0
|
|
and all available properties set on it:
|
|
.Pp
|
|
.Bd -literal
|
|
\&<key\&>device0\&<\&/key\&>
|
|
\&<array\&>
|
|
\&<dict\&>
|
|
\&<key\&>avg-value\&<\&/key\&>
|
|
\&<integer\&>36400\&<\&/integer\&>
|
|
\&<key\&>critical-capacity\&<\&/key\&>
|
|
\&<integer\&>21417\&<\&/integer\&>
|
|
\&<key\&>critical-max-limit\&<\&/key\&>
|
|
\&<integer\&>343150000\&<\&/integer\&>
|
|
\&<key\&>critical-min-limit\&<\&/key\&>
|
|
\&<integer\&>288150000\&<\&/integer\&>
|
|
\&<key\&>cur-value\&<\&/key\&>
|
|
\&<integer\&>406000\&<\&/integer\&>
|
|
\&<key\&>description\&<\&/key\&>
|
|
\&<string\&>sensor0\&<\&/string\&>
|
|
\&<key\&>max-value\&<\&/key\&>
|
|
\&<integer\&>3894000\&<\&/integer\&>
|
|
\&<key\&>min-value\&<\&/key\&>
|
|
\&<integer\&>2894000\&<\&/integer\&>
|
|
\&<key\&>monitoring-state-critical\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>monitoring-state-critover\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>monitoring-state-critunder\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>monitoring-state-warnover\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>monitoring-state-warnunder\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>monitoring-supported\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>state\&<\&/key\&>
|
|
\&<string\&>valid\&<\&/string\&>
|
|
\&<key\&>type\&<\&/key\&>
|
|
\&<string\&>Ampere hour\&<\&/string\&>
|
|
\&<key\&>want-percentage\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<\&/dict\&>
|
|
\&<\&/array\&>
|
|
.Ed
|
|
.Pp
|
|
Let's explain some more about those objects:
|
|
.Bl -tag -width "monitoring-state-critical-overxx"
|
|
.It Fa avg-value
|
|
Current average value in the sensor.
|
|
.It Fa critical-capacity
|
|
Critical capacity set previously by the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 .
|
|
Only available on sensors with the
|
|
.Em want-percentage
|
|
object enabled.
|
|
.It Fa critical-max-limit
|
|
Critical max limit set previously by the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 .
|
|
.It Fa critical-min-limit
|
|
Critical min limit set previously by the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 .
|
|
.It Fa cur-value
|
|
Current value in the sensor.
|
|
.It Fa description
|
|
Description of the sensor.
|
|
.It Fa max-value
|
|
Current max value in the sensor.
|
|
.It Fa min-value
|
|
Current min value in the sensor.
|
|
.It Fa monitoring-state-critical
|
|
If true, the driver has enabled the flag to monitor a critical state.
|
|
.It Fa monitoring-state-critical-over
|
|
If true, the driver has enabled the flag to monitor a critical over state.
|
|
.It Fa monitoring-state-critical-under
|
|
If true, the driver has enabled the flag to monitor a critical under state.
|
|
.It Fa monitoring-state-warning-over
|
|
If true, the driver has enabled the flag to monitor a warning over state.
|
|
.It Fa monitoring-state-warning-under
|
|
If true, the driver has enabled the flag to monitor a warning under state.
|
|
.It Fa monitoring-supported
|
|
If true, critical capacity/max/min limits may be set by the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 .
|
|
.It Fa state
|
|
Current state in the sensor.
|
|
.It Fa type
|
|
Type of unit in the sensor.
|
|
.It Fa want-percentage
|
|
If true,
|
|
.Em max-value
|
|
and
|
|
.Em cur-value
|
|
are valid and a percentage may be computed from them.
|
|
.El
|
|
.El
|
|
.Pp
|
|
.Bl -tag -width XX -compact
|
|
.It Dv ENVSYS_SETDICTIONARY (prop_dictionary_t)
|
|
.Pp
|
|
This
|
|
.Xr ioctl 2
|
|
is used to send a dictionary with new properties that should be
|
|
processed by the
|
|
.Nm
|
|
framework. Only a set of predefined keywords are recognized by
|
|
the kernel part. The following is the property list representation
|
|
of a dictionary with all recognized and required keywords:
|
|
.Bd -literal
|
|
\&<dict\&>
|
|
\&<key\&>driver-name\&<\&/key\&>
|
|
\&<string\&>driver0\&<\&/string\&>
|
|
\&<key\&>sensor-name\&<\&/key\&>
|
|
\&<string\&>sensor0\&<\&/string\&>
|
|
\&<key\&>new-description\&<\&/key\&>
|
|
\&<string\&>mysensor0\&<\&/string\&>
|
|
\&<key\&>new-rfact\&<\&/key\&>
|
|
\&<integer\&>56000\&<\&/integer\&>
|
|
\&<key\&>critical-capacity\&<\&/key\&>
|
|
\&<integer\&>10\&<\&/integer\&>
|
|
\&<key\&>critical-max-limit\&<\&/key\&>
|
|
\&<integer\&>3400\&<\&/integer\&>
|
|
\&<key\&>critical-min-limit\&<\&/key\&>
|
|
\&<integer\&>2800\&<\&/integer\&>
|
|
\&<key\&>remove-critical-cap\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>remove-cmax-limit\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<key\&>remove-cmin-limit\&<\&/key\&>
|
|
\&<true\&/\&>
|
|
\&<\&/dict\&>
|
|
.Ed
|
|
.Pp
|
|
A dictionary sent to the kernel with this
|
|
.Xr ioctl 2
|
|
must
|
|
.Sy always
|
|
have the objects
|
|
.Ar driver-name
|
|
and
|
|
.Ar sensor-name .
|
|
They are used to specify the
|
|
.Sy driver
|
|
and the
|
|
.Sy sensor
|
|
that we want to set a property for.
|
|
.Pp
|
|
.Em NOTE:
|
|
Only one of the following objects must be added into the dictionary
|
|
at a time:
|
|
.Ar new-description ,
|
|
.Ar new-rfact ,
|
|
.Ar critical-capacity ,
|
|
.Ar critical-max-limit ,
|
|
.Ar critical-min-limit ,
|
|
.Ar remove-critical-cap ,
|
|
.Ar remove-cmax-limit ,
|
|
and
|
|
.Ar remove-cmin-limit .
|
|
.Pp
|
|
The following operation is selected depending what object
|
|
was added into the dictionary:
|
|
.Pp
|
|
.Bl -bullet -offset indent -compact
|
|
.It
|
|
change a description.
|
|
.It
|
|
change the rfact in a voltage sensor.
|
|
.It
|
|
set a critical capacity limit.
|
|
.It
|
|
set a critical max limit.
|
|
.It
|
|
set a critical min limit.
|
|
.It
|
|
remove a critical capacity limit.
|
|
.It
|
|
remove a critical max limit.
|
|
.It
|
|
remove a critical min limit.
|
|
.El
|
|
.Pp
|
|
If an unknown object was sent with the dictionary,
|
|
.Er EINVAL
|
|
will be returned, or if the sensor does not support changing
|
|
rfact (voltage sensors) or critical/capacity limits,
|
|
.Er ENOTSUP
|
|
will be returned.
|
|
.El
|
|
.Pp
|
|
.Sh NOTES
|
|
When setting a critical max or min limit with the
|
|
.Em ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 ,
|
|
the user must be aware that
|
|
.Xr sysmon_envsys 9
|
|
expects to have a proper unit, so the value must be converted. Please
|
|
see
|
|
.Xr sysmon_envsys 9
|
|
for more information.
|
|
.Pp
|
|
Also when setting a critical capacity limit, the formula to send a
|
|
proper value to
|
|
.Xr sysmon_envsys 9
|
|
is the following:
|
|
.Em value = (value / 100) * max value .
|
|
The max value is available in the sensor's dictionary.
|
|
.Pp
|
|
.Sh EXAMPLES
|
|
The following example illustrates how to receive the dictionary
|
|
and to print it in raw XML/plist format:
|
|
.Bd -literal
|
|
#define _DEV_SYSMON /dev/sysmon
|
|
|
|
int main(void)
|
|
{
|
|
prop_dictionary_t dict;
|
|
int fd;
|
|
|
|
if ((fd = open(_DEV_SYSMON, O_RDONLY)) == -1)
|
|
err(EXIT_FAILURE, "open")
|
|
|
|
if (prop_dictionary_recv_ioctl(fd, ENVSYS_GETDICTIONARY, &dict)) {
|
|
(void)close(fd);
|
|
err(EINVAL, "prop_dictionary_recv_ioctl");
|
|
}
|
|
|
|
(void)printf("%s", prop_dictionary_externalize(dict));
|
|
prop_object_release(dict);
|
|
(void)close(fd);
|
|
|
|
return EXIT_SUCCESS;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Another example that shows how to use the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2
|
|
to change the description in a sensor:
|
|
.Bd -literal
|
|
int
|
|
main(void)
|
|
{
|
|
prop_dictionary_t dict;
|
|
prop_object_t obj;
|
|
int fd;
|
|
|
|
dict = prop_dictionary_create();
|
|
|
|
obj = prop_string_create_cstring_nocopy("aiboost0");
|
|
if (obj == NULL ||
|
|
!prop_dictionary_set(dict, "driver-name", obj))
|
|
err(EINVAL, "driver-name");
|
|
|
|
prop_object_release(obj);
|
|
|
|
obj = prop_string_create_cstring_nocopy("CPU Temperature");
|
|
if (obj == NULL ||
|
|
!prop_dictionary_set(dict, "sensor-name", obj))
|
|
err(EINVAL, "sensor-name");
|
|
|
|
prop_object_release(obj);
|
|
|
|
/* new description */
|
|
obj = prop_string_create_cstring_nocopy("CPU temp");
|
|
if (obj == NULL ||
|
|
!prop_dictionary_set(dict, "new-description", obj))
|
|
err(EINVAL, "new-description");
|
|
|
|
prop_object_release(obj);
|
|
|
|
if ((fd = open(_DEV_SYSMON, O_RDONLY)) == -1)
|
|
err(EXIT_FAILURE, "open")
|
|
|
|
/* we are done, send the dictionary */
|
|
error = prop_dictionary_send_ioctl(dict,
|
|
fd,
|
|
ENVSYS_SETDICTIONARY);
|
|
prop_object_release(dict);
|
|
(void)close(fd);
|
|
return error;
|
|
}
|
|
.Ed
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
2 framework was designed and implemented by
|
|
.An Juan Romero Pardines
|
|
for
|
|
.Nx 5.0 .
|
|
Many useful comments for this framework were from
|
|
Jason R. Thorpe, Tim Rightnour and Michael Lorenz. Previous
|
|
framework was implemented by Tim Rightnour and Bill Squier.
|
|
.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 proplib 3 ,
|
|
.Xr sparc/tctrl 4 ,
|
|
.Xr sparc64/envctrl 4 ,
|
|
.Xr tm121temp 4 ,
|
|
.Xr ug 4 ,
|
|
.Xr viaenv 4 ,
|
|
.Xr envstat 8
|
|
.Xr sysmon_envsys 9 ,
|
|
.Xr sysmon_power 9
|