ENVSYS(4) | Device Drivers Manual | ENVSYS(4) |
envsys
—
#include <sys/envsys.h>
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 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> <key>index</key> <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:
ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object
enabled.ENVSYS_SETDICTIONARY
ioctl(2).ENVSYS_SETDICTIONARY
ioctl(2).ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object enabled.
Used to monitor possible over-charging of batteries.ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object enabled.
Used to monitor possible over-charging of batteries.ENVSYS_SETDICTIONARY
ioctl(2).ENVSYS_SETDICTIONARY
ioctl(2). Only available
on sensors with the want-percentage object
enabled.ENVSYS_SETDICTIONARY
ioctl(2).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)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.
Additionally, the following
ioctl(2) commands are provided
for compatibility purposes for applications written against the original
experimental envsys
API available between
NetBSD 1.5 and NetBSD 4.0;
they have been deprecated since NetBSD 5.0, and may
be removed at any time:
ENVSYS_GTREDATA
(envsys_tre_data_t)ENVSYS_GTREINFO
(envsys_basic_info_t)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.
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; }
The first envsys framework was implemented by Jason R. Thorpe, Tim Rightnour, and Bill Squier.
January 10, 2013 | NetBSD 9.4 |