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:
- the userland part, to receive
the current sensor data and to set some properties on sensors:
envstat(8).
- The kernel part that is able
to talk to the devices 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 contain an array of dictionaries per device and one
dictionary per sensor plus another special dictionary that contains the
properties for a device. Each sensor dictionary will have its own
characteristics and values.
The following XML property list represents a virtual device
“device0” with one entry for sensor “sensor0” and
all available properties set on it, plus another entry for the
“device-properties” dictionary (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>
<key>high-capacity</key>
<integer>21417</integer>
<string>index</string>
<string>sensor0</string>
<key>max-value</key>
<integer>3894000</integer>
<key>maximum-capacity</key>
<integer>21417</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/>
<key>warning-capacity</key>
<integer>19234</integer>
<key>warning-max</key>
<integer>323150000</integer>
<key>warning-min</key>
<integer>298150000</integer>
</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 means that the sensor is
able to change the resistor factor, only used in Voltage sensors.
-
-
- avg-value
- Current average value in the sensor.
-
-
- battery-capacity
- Current capacity state for a battery 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.
-
-
- high-capacity
- High capacity set previously by the
ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object enabled.
Used to monitor possible over-charging of batteries.
-
-
- index
- Index position of the sensor.
-
-
- max-value
- Current max value in the sensor.
-
-
- maximum-capacity
- Maximum capacity set previously by the
ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object enabled.
Used to monitor possible over-charging of batteries.
-
-
- min-value
- Current min value in the sensor.
-
-
- monitoring-state-critical
- If true, the device has enabled the flag to monitor a
critical state.
-
-
- monitoring-state-hw-range-limits
- If true, the device has enabled the flag to monitor
warning or critical limits.
-
-
- monitoring-state-state-changed
- If true, the device has enabled the flag to monitor for
state changes in a drive or Battery state sensor.
-
-
- monitoring-supported
- If true, critical/warning 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.
-
-
- warning-capacity
- Warning capacity set previously by the
ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object
enabled.
-
-
- warning-max
- Warning max limit set previously by the
ENVSYS_SETDICTIONARY
ioctl(2).
-
-
- warning-min
- Warning min limit set previously by the
ENVSYS_SETDICTIONARY
ioctl(2).
-
-
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 device 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 predefined
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>
<key>high-capacity</key>
<integer>95</integer>
<key>maximum-capacity</key>
<integer>100</integer>
<key>warning-capacity</key>
<integer>15</integer>
<key>warning-max</key>
<integer>3200</integer>
<key>warning-min</key>
<integer>2900</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 following 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/warning/capacity
limits, ENOTSUP
will be returned.
NOTES
When setting a critical/warning 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 or warning 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
‘
aibs0
’ 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, error;
global_dict = prop_dictionary_create();
sensor_dict = prop_dictionary_create();
array = prop_array_create();
if (!prop_dictionary_set(global_dict, "aibs0", array))
err(EINVAL, "prop_dictionary_set global");
obj = prop_string_create_cstring_nocopy("sensor0");
if (obj == NULL ||
!prop_dictionary_set(sensor_dict, "index", obj))
err(EINVAL, "sensor index");
prop_object_release(obj);
/* new description */
obj = prop_string_create_cstring_nocopy("CPU core voltage");
if (obj == NULL ||
!prop_dictionary_set(sensor_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
envsys.conf(5),
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 Rightnour, and Bill Squier.