Home | History | Annotate | Line # | Download | only in man4
envsys.4 revision 1.36 
 $NetBSD: envsys.4,v 1.36 2007/10/07 05:33:06 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 October 7, 2007
.Dt ENVSYS 4
.Os
.Sh NAME
.Nm envsys
.Nd Environmental Systems framework (version 2)
.Sh SYNOPSIS
n sys/envsys.h .Sh DESCRIPTION
The
.Nm
framework provides support to handle hardware monitor sensors.
Hardware monitoring chips are able to report values from different types of
sensors.

p
The
.Nm
framework consists of two parts:

p
l -enum -offset indent -compact t the userland part, to receive the current sensor data and
to set some properties on sensors:
.Nm .
t the kernel part that is able to talk to the drivers providing sensor
data:
.Xr sysmon_envsys 9 .
.El

p
The
.Nm
framework uses
.Xr proplib 3
for communication between kernel and user space. The following
.Xr ioctl 2
types are available:

p
l -tag -width XX -compact t Dv ENVSYS_GETDICTIONARY (prop_dictionary_t) 
p
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.

p
The following XML property list represents a virtual device
.Dq device0
with one sensor
.Dq sensor0
and all available properties set on it:

p
d -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-state\*[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

p
Let's explain some more about those objects:
l -tag -width "monitoring-state-critical-overxx" t Fa allow-rfact Set to
.Em true
mean that the sensor is able to change the resistor factor,
only used in Voltage sensors.
t Fa avg-value Current average value in the sensor.
t Fa battery-state Current state for a battery state sensor.
t 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.
t Fa critical-max Critical max limit set previously by the
.Ar ENVSYS_SETDICTIONARY
.Xr ioctl 2 .
t Fa critical-min Critical min limit set previously by the
.Ar ENVSYS_SETDICTIONARY
.Xr ioctl 2 .
t Fa cur-value Current value in the sensor.
t Fa description Description of the sensor.
t Fa index Index position of the sensor.
t Fa max-value Current max value in the sensor.
t Fa min-value Current min value in the sensor.
t Fa monitoring-state-critical If true, the driver has enabled the flag to monitor a critical state.
t Fa monitoring-state-critical-over If true, the driver has enabled the flag to monitor a critical over state.
t Fa monitoring-state-critical-under If true, the driver has enabled the flag to monitor a critical under state.
t 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.
t Fa monitoring-state-warning-over If true, the driver has enabled the flag to monitor a warning over state.
t Fa monitoring-state-warning-under If true, the driver has enabled the flag to monitor a warning under state.
t Fa monitoring-supported If true, critical capacity/max/min limits may be set by the
.Ar ENVSYS_SETDICTIONARY
.Xr ioctl 2 .
t Fa state Current state in the sensor.
t Fa type Type of unit in the sensor.
t Fa want-percentage If true,
.Em max-value
and
.Em cur-value
are valid and a percentage may be computed from them.
.El
.El

p
l -tag -width XX -compact t Dv ENVSYS_REMOVEPROPS (prop_dictionary_t) 
p
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.

p
Only one object is allowed on this dictionary:
d -literal -offset -ident  <key>envsys-remove-props</key>
 <true/>
.Ed

p
It is a boolean object and must be set to
.Em true
to be effective.
.El
l -tag -width XX -compact 
p
t Dv ENVSYS_SETDICTIONARY (prop_dictionary_t) 
p
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:
d -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

p
A dictionary sent to the kernel with this
.Xr ioctl 2
should have the following structure:
d -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

p
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.

p
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.

p
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

p
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 :
d -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 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.