diff options
Diffstat (limited to 'static/netbsd/man4/envsys.4 3.html')
| -rw-r--r-- | static/netbsd/man4/envsys.4 3.html | 403 |
1 files changed, 0 insertions, 403 deletions
diff --git a/static/netbsd/man4/envsys.4 3.html b/static/netbsd/man4/envsys.4 3.html deleted file mode 100644 index d0b213c1..00000000 --- a/static/netbsd/man4/envsys.4 3.html +++ /dev/null @@ -1,403 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">ENVSYS(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">ENVSYS(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">envsys</code> — - <span class="Nd">Environmental Systems framework (version 2)</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/envsys.h</a>></code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">envsys</code> framework provides support to - handle hardware monitor devices. Hardware monitoring chips are able to - report values from different types of sensors.</p> -<p class="Pp">The <code class="Nm">envsys</code> framework consists of two - parts:</p> -<p class="Pp"></p> -<ol class="Bl-enum Bd-indent Bl-compact"> - <li>the userland part, to receive the current sensor data and to set some - properties on sensors: <a class="Xr">envstat(8)</a>.</li> - <li>The kernel part that is able to talk to the devices providing sensor data: - <a class="Xr">sysmon_envsys(9)</a>.</li> -</ol> -<p class="Pp">The <code class="Nm">envsys</code> framework uses - <a class="Xr">proplib(3)</a> for communication between kernel and user - space. The following <a class="Xr">ioctl(2)</a> types are available:</p> -<dl class="Bl-tag"> - <dt id="ENVSYS_GETDICTIONARY"><a class="permalink" href="#ENVSYS_GETDICTIONARY"><code class="Dv">ENVSYS_GETDICTIONARY</code></a> - (prop_dictionary_t)</dt> - <dd> - <p class="Pp">This <a class="Xr">ioctl(2)</a> is used to receive the global - dictionary that is being used in the kernel by the - <a class="Xr">sysmon_envsys(9)</a> 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.</p> - <p class="Pp">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):</p> - <div class="Bd Pp Li"> - <pre><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></pre> - </div> - <p class="Pp">Let's explain some more about those objects:</p> - <dl class="Bl-tag"> - <dt><var class="Fa">allow-rfact</var></dt> - <dd>Set to <i class="Em">true</i> means that the sensor is able to change - the resistor factor, only used in Voltage sensors.</dd> - <dt><var class="Fa">avg-value</var></dt> - <dd>Current average value in the sensor.</dd> - <dt><var class="Fa">battery-capacity</var></dt> - <dd>Current capacity state for a battery capacity sensor.</dd> - <dt><var class="Fa">critical-capacity</var></dt> - <dd>Critical capacity set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>. Only available on sensors with the - <i class="Em">want-percentage</i> object enabled.</dd> - <dt><var class="Fa">critical-max</var></dt> - <dd>Critical max limit set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>.</dd> - <dt><var class="Fa">critical-min</var></dt> - <dd>Critical min limit set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>.</dd> - <dt><var class="Fa">cur-value</var></dt> - <dd>Current value in the sensor.</dd> - <dt><var class="Fa">description</var></dt> - <dd>Description of the sensor.</dd> - <dt><var class="Fa">high-capacity</var></dt> - <dd>High capacity set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>. Only available on sensors with the - <i class="Em">want-percentage</i> object enabled. Used to monitor - possible over-charging of batteries.</dd> - <dt><var class="Fa">index</var></dt> - <dd>Index position of the sensor.</dd> - <dt><var class="Fa">max-value</var></dt> - <dd>Current max value in the sensor.</dd> - <dt><var class="Fa">maximum-capacity</var></dt> - <dd>Maximum capacity set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>. Only available on sensors with the - <i class="Em">want-percentage</i> object enabled. Used to monitor - possible over-charging of batteries.</dd> - <dt><var class="Fa">min-value</var></dt> - <dd>Current min value in the sensor.</dd> - <dt><var class="Fa">monitoring-state-critical</var></dt> - <dd>If true, the device has enabled the flag to monitor a critical - state.</dd> - <dt><var class="Fa">monitoring-state-hw-range-limits</var></dt> - <dd>If true, the device has enabled the flag to monitor warning or - critical limits.</dd> - <dt><var class="Fa">monitoring-state-state-changed</var></dt> - <dd>If true, the device has enabled the flag to monitor for state changes - in a drive or Battery state sensor.</dd> - <dt><var class="Fa">monitoring-supported</var></dt> - <dd>If true, critical/warning capacity/max/min limits may be set by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>.</dd> - <dt><var class="Fa">state</var></dt> - <dd>Current state in the sensor.</dd> - <dt><var class="Fa">type</var></dt> - <dd>Type of unit in the sensor.</dd> - <dt id="max-value"><var class="Fa">want-percentage</var></dt> - <dd>If true, - <a class="permalink" href="#max-value"><i class="Em">max-value</i></a> - and - <a class="permalink" href="#cur-value"><i class="Em" id="cur-value">cur-value</i></a> - are valid and a percentage may be computed from them.</dd> - <dt><var class="Fa">warning-capacity</var></dt> - <dd>Warning capacity set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>. Only available on sensors with the - <i class="Em">want-percentage</i> object enabled.</dd> - <dt><var class="Fa">warning-max</var></dt> - <dd>Warning max limit set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>.</dd> - <dt><var class="Fa">warning-min</var></dt> - <dd>Warning min limit set previously by the - <code class="Dv">ENVSYS_SETDICTIONARY</code> - <a class="Xr">ioctl(2)</a>.</dd> - </dl> - </dd> - <dt id="ENVSYS_REMOVEPROPS"><a class="permalink" href="#ENVSYS_REMOVEPROPS"><code class="Dv">ENVSYS_REMOVEPROPS</code></a> - (prop_dictionary_t)</dt> - <dd> - <p class="Pp">This <a class="Xr">ioctl(2)</a> is used to remove all - properties that are currently set via the - <code class="Dv">ENVSYS_SETDICTIONARY</code> ioctl. The values will be - set to defaults, the ones that the device uses.</p> - <p class="Pp">Only one object is allowed on this dictionary:</p> - <div class="Bd Pp Bd-indent Li"> - <pre><key>envsys-remove-props</key> -<true/></pre> - </div> - <p class="Pp">It is a boolean object and must be set to - <i class="Em">true</i> to be effective.</p> - </dd> - <dt id="ENVSYS_SETDICTIONARY"><a class="permalink" href="#ENVSYS_SETDICTIONARY"><code class="Dv">ENVSYS_SETDICTIONARY</code></a> - (prop_dictionary_t)</dt> - <dd>This <a class="Xr">ioctl(2)</a> is used to send a dictionary with new - properties that should be processed by the <code class="Nm">envsys</code> - 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: - <div class="Bd Pp Li"> - <pre><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></pre> - </div> - <p class="Pp">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:</p> - <div class="Bd Pp Li"> - <pre><dict> - <key>device-properties</key> - <dict> - <key>refresh-timeout</key> - <integer>0xa</integer> - </dict> -</dict></pre> - </div> - <p class="Pp">A dictionary sent to the kernel with this - <a class="Xr">ioctl(2)</a> should have the following structure:</p> - <div class="Bd Pp Li"> - <pre><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></pre> - </div> - <p class="Pp" id="index">The named device will be an array and will contain - dictionaries, any dictionary needs to have the - <a class="permalink" href="#index"><i class="Em">index</i></a> object - specifying the sensor that is required for the new properties.</p> - <p class="Pp">If an unknown object was sent with the dictionary, - <code class="Er">EINVAL</code> will be returned, or if the sensor does - not support changing rfact (voltage sensors) or - critical/warning/capacity limits, <code class="Er">ENOTSUP</code> will - be returned.</p> - </dd> -</dl> -<p class="Pp">Additionally, the following <a class="Xr">ioctl(2)</a> commands - are provided for compatibility purposes for applications written against the - original experimental <code class="Nm">envsys</code> API available between - <span class="Ux">NetBSD 1.5</span> and <span class="Ux">NetBSD 4.0</span>; - they have been deprecated since <span class="Ux">NetBSD 5.0</span>, and may - be removed at any time:</p> -<dl class="Bl-tag"> - <dt id="ENVSYS_GTREDATA"><a class="permalink" href="#ENVSYS_GTREDATA"><code class="Dv">ENVSYS_GTREDATA</code></a> - (envsys_tre_data_t)</dt> - <dd style="width: auto;"> </dd> - <dt id="ENVSYS_GTREINFO"><a class="permalink" href="#ENVSYS_GTREINFO"><code class="Dv">ENVSYS_GTREINFO</code></a> - (envsys_basic_info_t)</dt> - <dd style="width: auto;"> </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> -<p class="Pp">When setting a critical/warning max or min limit with the - <code class="Dv">ENVSYS_SETDICTIONARY</code> <a class="Xr">ioctl(2)</a>, the - user must be aware that <a class="Xr">sysmon_envsys(9)</a> expects to have a - proper unit, so the value must be converted. Please see - <a class="Xr">sysmon_envsys(9)</a> for more information.</p> -<p class="Pp" id="value">Also when setting a critical or warning capacity limit, - the formula to send a proper value to <a class="Xr">sysmon_envsys(9)</a> is - the following: <a class="permalink" href="#value"><i class="Em">value = - (value / 100) * max value</i></a>. The max value is available in the - sensor's dictionary.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">The following example shows how to change the description of - ‘<code class="Li">sensor0</code>’ in the - ‘<code class="Li">aibs0</code>’ device with the - <code class="Dv">ENVSYS_SETDICTIONARY</code> <a class="Xr">ioctl(2)</a>:</p> -<div class="Bd Pp Li"> -<pre>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; -}</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">envsys.conf(5)</a>, <a class="Xr">envstat(8)</a>, - <a class="Xr">powerd(8)</a>, <a class="Xr">sysmon_envsys(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The first <i class="Em">envsys</i> framework first appeared in - <span class="Ux">NetBSD 1.5</span>. The <i class="Em">envsys 2</i> framework - first appeared in <span class="Ux">NetBSD 5.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The (current) <i class="Em">envsys 2</i> framework was implemented - by <span class="An">Juan Romero Pardines</span>. Additional input on the - design was provided by many <span class="Ux">NetBSD</span> developers around - the world.</p> -<p class="Pp">The first <i class="Em">envsys</i> framework was implemented by - Jason R. Thorpe, Tim Rightnour, and Bill Squier.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">May 4, 2021</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |