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 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 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” dictionary (which contains specific properties for a device):

        keydevice0/key
        array
        	dict
        		keyallow-rfact/key
        		true/
        		keyavg-value/key
        		integer36400/integer
        		keybattery-capacity/key
        		stringNORMAL/string
        		keycritical-capacity/key
        		integer21417/integer
        		keycritical-max/key
        		integer343150000/integer
        		keycritical-min/key
        		integer288150000/integer
        		keycur-value/key
        		integer406000/integer
        		keydescription/key
        		stringCPU Temp/string
        		stringindex/string
        		stringsensor0/string
        		keymax-value/key
        		integer3894000/integer
        		keymin-value/key
        		integer2894000/integer
        		keymonitoring-state-critical/key
        		true/
        		keymonitoring-state-critover/key
        		true/
        		keymonitoring-state-critunder/key
        		true/
        		keymonitoring-state-state-changed/key
        		true/
        		keymonitoring-state-warnover/key
        		true/
        		keymonitoring-state-warnunder/key
        		true/
        		keymonitoring-supported/key
        		true/
        		keystate/key
        		stringvalid/string
        		keytype/key
        		stringAmpere hour/string
        		keywant-percentage/key
        		true/
        	/dict
        	dict
        		keydevice-properties/key
        		dict
        			keyrefresh-timeout/key
        			integer0xa/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 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.

    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:

        	keyenvsys-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
        	keydescription/key
        	stringcpu temp/string
        	keyrfact/key
        	integer56000/integer
        	keycritical-capacity/key
        	integer10/integer
        	keycritical-max/key
        	integer3400/integer
        	keycritical-min/key
        	integer2800/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
        	keydevice-properties/key
        	dict
        		keyrefresh-timeout/key
        		integer0xa/integer
        	/dict
        /dict

    A dictionary sent to the kernel with this ioctl(2) should have the following structure:

        dict
        	keydevice_name/key
        	array
        		dict
        			keyindex/key
        			stringsensor0/string
        			keydescription/key
        			stringcpu 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 Rightnour, and Bill Squier.