Unix/Linux Go Back    


NetBSD 6.1.5 - man page for envsys (netbsd section 4)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ENVSYS(4)			   BSD Kernel Interfaces 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 monitor-
     ing 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 proper-
	 ties for a device.  Each sensor dictionary will have their own characteristics and val-
	 ues.

	 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):

	 <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 sen-
					   sors 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 sen-
					   sors 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 sen-
					   sors 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 per-
					   centage may be computed from them.

	 warning-capacity		   Warning capacity set previously by the
					   ENVSYS_SETDICTIONARY ioctl(2).  Only available on sen-
					   sors 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 recog-
	 nized 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'' dic-
	 tionary must be used.	At this moment only the ``refresh-timeout'' property is under-
	 stood.  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.

BSD					  March 14, 2010				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:06 PM.