Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


ENVSYS(4)                    Device Drivers 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 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>
                         <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:

         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.

     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)

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_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(_PATH_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(sensor_dict);
             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.

NetBSD 10.99                      May 4, 2021                     NetBSD 10.99