ENVSYS(4)

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.

May 4, 2021 | NetBSD 11.0