envsys(4)
- NetBSD Manual Pages
ENVSYS(4) NetBSD Kernel Interfaces Manual ENVSYS(4)
NAME
envsys -- Environmental Systems framework (version 2)
SYNOPSIS
#include <sys/envsys.h>
DESCRIPTION
The envsys framework provides support to handle hardware monitor devices.
Hardware monitoring chips are able to report values from different types
of sensors.
The envsys framework consists of two parts:
1. the userland part, to receive the current sensor data and to
set some properties on sensors: envstat(8).
2. The kernel part that is able to talk to the drivers providing
sensor data: sysmon_envsys(9).
The envsys framework uses proplib(3) for communication between kernel and
user space. The following ioctl(2) types are available:
ENVSYS_GETDICTIONARY (prop_dictionary_t)
This ioctl(2) is used to receive the global dictionary that is being
used in the kernel by the sysmon_envsys(9) framework. It will con-
tain an array of dictionaries per device and one dictionary per sen-
sor plus another special dictionary that contains the properties for
a device. Each sensor dictionary will have their own characteristics
and values.
The following XML property list represents a virtual device
``device0'' with one sensor ``sensor0'' and all available properties
set on it, plus another sensor for the ``device-properties'' dictio-
nary (which contains specific properties for a device):
<key>device0</key>
<array>
<dict>
<key>allow-rfact</key>
<true/>
<key>avg-value</key>
<integer>36400</integer>
<key>battery-capacity</key>
<string>NORMAL</string>
<key>critical-capacity</key>
<integer>21417</integer>
<key>critical-max</key>
<integer>343150000</integer>
<key>critical-min</key>
<integer>288150000</integer>
<key>cur-value</key>
<integer>406000</integer>
<key>description</key>
<string>CPU Temp</string>
<string>index</string>
<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-state-changed</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>
<dict>
<key>device-properties</key>
<dict>
<key>refresh-timeout</key>
<integer>0xa</integer>
</dict>
</dict>
</array>
Let's explain some more about those objects:
allow-rfact Set to true mean that the sensor is
able to change the resistor factor,
only used in Voltage sensors.
avg-value Current average value in the sen-
sor.
battery-capacity Current capacity state for a bat-
tery capacity sensor.
critical-capacity Critical capacity set previously by
the ENVSYS_SETDICTIONARY ioctl(2).
Only available on sensors with the
want-percentage object enabled.
critical-max Critical max limit set previously
by the ENVSYS_SETDICTIONARY
ioctl(2).
critical-min Critical min limit set previously
by the ENVSYS_SETDICTIONARY
ioctl(2).
cur-value Current value in the sensor.
description Description of the sensor.
index Index position of the sensor.
max-value Current max value in the sensor.
min-value Current min value in the sensor.
monitoring-state-critical If true, the driver has enabled the
flag to monitor a critical state.
monitoring-state-critical-over If true, the driver has enabled the
flag to monitor a critical over
state.
monitoring-state-critical-under If true, the driver has enabled the
flag to monitor a critical under
state.
monitoring-state-state-changed If true, the driver has enabled the
flag to monitor for state changes
in a drive or Battery state sensor.
monitoring-state-warning-over If true, the driver has enabled the
flag to monitor a warning over
state.
monitoring-state-warning-under If true, the driver has enabled the
flag to monitor a warning under
state.
monitoring-supported If true, critical capacity/max/min
limits may be set by the
ENVSYS_SETDICTIONARY ioctl(2).
state Current state in the sensor.
type Type of unit in the sensor.
want-percentage If true, max-value and cur-value
are valid and a percentage may be
computed from them.
ENVSYS_REMOVEPROPS (prop_dictionary_t)
This ioctl(2) is used to remove all properties that are currently set
via the ENVSYS_SETDICTIONARY ioctl. The values will be set to
defaults, the ones that the driver uses.
Only one object is allowed on this dictionary:
<key>envsys-remove-props</key>
<true/>
It is a boolean object and must be set to true to be effective.
ENVSYS_SETDICTIONARY (prop_dictionary_t)
This ioctl(2) is used to send a dictionary with new properties that
should be processed by the envsys framework. Only a set of prede-
fined keywords are recognized by the kernel part. The following is
the property list representation of a dictionary with all recognized
and required keywords that a sensor understands:
<dict>
<key>description</key>
<string>cpu temp</string>
<key>rfact</key>
<integer>56000</integer>
<key>critical-capacity</key>
<integer>10</integer>
<key>critical-max</key>
<integer>3400</integer>
<key>critical-min</key>
<integer>2800</integer>
</dict>
Also if some properties in a device need to be changed, the
``device-properties'' dictionary must be used. At this moment only
the ``refresh-timeout'' property is understood. This has the follow-
ing structure:
<dict>
<key>device-properties</key>
<dict>
<key>refresh-timeout</key>
<integer>0xa</integer>
</dict>
</dict>
A dictionary sent to the kernel with this ioctl(2) should have the
following structure:
<dict>
<key>device_name</key>
<array>
<dict>
<key>index</key>
<string>sensor0</string>
<key>description</key>
<string>cpu temp</string>
...
Another property for this sensor
...
</dict>
...
Another dictionary for device-properties or sensor
...
</array>
...
Another device as above
...
</dict>
The named device will be an array and will contain dictionaries, any
dictionary needs to have the index object specifying the sensor that
is required for the new properties.
If an unknown object was sent with the dictionary, EINVAL will be
returned, or if the sensor does not support changing rfact (voltage
sensors) or critical/capacity limits, ENOTSUP will be returned.
NOTES
When setting a critical max or min limit with the ENVSYS_SETDICTIONARY
ioctl(2), the user must be aware that sysmon_envsys(9) expects to have a
proper unit, so the value must be converted. Please see sysmon_envsys(9)
for more information.
Also when setting a critical capacity limit, the formula to send a proper
value to sysmon_envsys(9) is the following: value = (value / 100) * max
value. The max value is available in the sensor's dictionary.
EXAMPLES
The following example shows how to change the description of `sensor0' in
the `aiboost0' device with the ENVSYS_SETDICTIONARY ioctl(2):
int
main(void)
{
prop_dictionary_t global_dict, sensor_dict;
prop_array_t array;
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;
}
SEE ALSO
envstat(8), powerd(8), sysmon_envsys(9)
HISTORY
The first envsys framework first appeared in NetBSD 1.5. The envsys 2
framework first appeared in NetBSD 5.0.
AUTHORS
The (current) envsys 2 framework was implemented by Juan Romero Pardines.
Additional input on the design was provided by many NetBSD developers
around the world.
The first envsys framework was implemented by Jason R. Thorpe, Tim Right-
nour, and Bill Squier.
NetBSD 5.0.1 November 13, 2007 NetBSD 5.0.1
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.