394 lines
12 KiB
Groff
394 lines
12 KiB
Groff
.\" $NetBSD: envsys.4,v 1.37 2007/11/03 23:05:56 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 November 1, 2007
|
|
.Dt ENVSYS 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm envsys
|
|
.Nd Environmental Systems framework (version 2)
|
|
.Sh SYNOPSIS
|
|
.In sys/envsys.h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
framework provides support to handle hardware monitor devices.
|
|
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 envstat 8 .
|
|
.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
|
|
\&\*[Lt]key\&\*[Gt]device0\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]array\&\*[Gt]
|
|
\&\*[Lt]dict\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]allow-rfact\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]avg-value\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]36400\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]battery-capacity\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]NORMAL\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]343150000\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]288150000\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]cur-value\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]406000\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]CPU Temp\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]index\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]max-value\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]3894000\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]min-value\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]2894000\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-state-critical\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-state-critover\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-state-critunder\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-state-state-changed\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-state-warnover\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-state-warnunder\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]monitoring-supported\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]state\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]valid\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]type\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]Ampere hour\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]want-percentage\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]true\&/\&\*[Gt]
|
|
\&\*[Lt]\&/dict\&\*[Gt]
|
|
\&\*[Lt]\&/array\&\*[Gt]
|
|
.Ed
|
|
.Pp
|
|
Let's explain some more about those objects:
|
|
.Bl -tag -width "monitoring-state-critical-overxx"
|
|
.It Fa allow-rfact
|
|
Set to
|
|
.Em true
|
|
mean that the sensor is able to change the resistor factor,
|
|
only used in Voltage sensors.
|
|
.It Fa avg-value
|
|
Current average value in the sensor.
|
|
.It Fa battery-capacity
|
|
Current capacity state for a battery capacity 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
|
|
Critical max limit set previously by the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 .
|
|
.It Fa critical-min
|
|
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 index
|
|
Index position 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-state-changed
|
|
If true, the driver has enabled the flag to monitor for state changes in
|
|
a drive or Battery state sensor.
|
|
.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_REMOVEPROPS (prop_dictionary_t)
|
|
.Pp
|
|
This
|
|
.Xr ioctl 2
|
|
is used to remove all properties that are currently set via the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
ioctl. The values will be set to defaults, the ones that the driver
|
|
uses.
|
|
.Pp
|
|
Only one object is allowed on this dictionary:
|
|
.Bd -literal -offset -ident
|
|
<key>envsys-remove-props</key>
|
|
<true/>
|
|
.Ed
|
|
.Pp
|
|
It is a boolean object and must be set to
|
|
.Em true
|
|
to be effective.
|
|
.El
|
|
.Bl -tag -width XX -compact
|
|
.Pp
|
|
.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
|
|
\&\*[Lt]dict\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]rfact\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]56000\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]10\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]3400\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]integer\&\*[Gt]2800\&\*[Lt]\&/integer\&\*[Gt]
|
|
\&\*[Lt]\&/dict\&\*[Gt]
|
|
.Ed
|
|
.Pp
|
|
A dictionary sent to the kernel with this
|
|
.Xr ioctl 2
|
|
should have the following structure:
|
|
.Bd -literal
|
|
\&\*[Lt]dict\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]device_name\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]array\&\*[Gt]
|
|
\&\*[Lt]dict\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]index\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt]
|
|
\&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt]
|
|
\&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt]
|
|
...
|
|
Another property for this sensor
|
|
...
|
|
\&\*[Lt]\&/dict\&\*[Gt]
|
|
...
|
|
Another dictionary for other sensor
|
|
...
|
|
\&\*[Lt]\&/array\&\*[Gt]
|
|
...
|
|
Another device as above
|
|
...
|
|
\&\*[Lt]\&/dict\&\*[Gt]
|
|
.Ed
|
|
.Pp
|
|
The named device will be an array and will contain dictionaries,
|
|
any dictionary needs to have the
|
|
.Em index
|
|
object specifying the sensor that is required for the new properties.
|
|
.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
|
|
.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.
|
|
.Sh EXAMPLES
|
|
.Pp
|
|
The following example shows how to change the description
|
|
of
|
|
.Ql sensor0
|
|
in the
|
|
.Ql aiboost0
|
|
device with the
|
|
.Ar ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 :
|
|
.Bd -literal
|
|
int
|
|
main(void)
|
|
{
|
|
prop_dictionary_t global_dict, sensor_dict;
|
|
prop_array_t;
|
|
prop_object_t obj;
|
|
int fd;
|
|
|
|
global_dict = prop_dictionary_create();
|
|
sensor_dict = prop_dictionary_create();
|
|
array = prop_array_create();
|
|
|
|
if (!prop_dictionary_set(global_dict, "aiboost0", array))
|
|
err(EINVAL, "prop_dictionary_set global");
|
|
|
|
obj = prop_string_create_cstring_nocopy("sensor0");
|
|
if (obj == NULL ||
|
|
!prop_dictionary_set(dict, "index", obj))
|
|
err(EINVAL, "sensor index");
|
|
|
|
prop_object_release(obj);
|
|
|
|
/* new description */
|
|
obj = prop_string_create_cstring_nocopy("CPU temp");
|
|
if (obj == NULL ||
|
|
!prop_dictionary_set(dict, "description", obj))
|
|
err(EINVAL, "new description");
|
|
|
|
prop_object_release(obj);
|
|
|
|
if (!prop_array_add(array, sensor_dict))
|
|
err(EINVAL, "prop_array_add");
|
|
|
|
if ((fd = open(_DEV_SYSMON, O_RDWR)) == -1)
|
|
err(EXIT_FAILURE, "open")
|
|
|
|
/* we are done, send the dictionary */
|
|
error = prop_dictionary_send_ioctl(global_dict,
|
|
fd,
|
|
ENVSYS_SETDICTIONARY);
|
|
prop_object_release(array);
|
|
prop_object_release(global_dict);
|
|
(void)close(fd);
|
|
return error;
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr envstat 8 ,
|
|
.Xr powerd 8 ,
|
|
.Xr sysmon_envsys 9
|
|
.Sh HISTORY
|
|
The first
|
|
.Em envsys
|
|
framework first appeared in
|
|
.Nx 1.5 .
|
|
The
|
|
.Em envsys 2
|
|
framework first appeared in
|
|
.Nx 5.0 .
|
|
.Sh AUTHORS
|
|
The (current)
|
|
.Em envsys 2
|
|
framework was implemented by
|
|
.An Juan Romero Pardines .
|
|
Additional input on the design was provided by many
|
|
.Nx
|
|
developers around the world.
|
|
.Pp
|
|
The first
|
|
.Em envsys
|
|
framework was implemented by Jason R. Thorpe, Tim Rightnour
|
|
and Bill Squier.
|