1.\" $NetBSD: envsys.4,v 1.48 2010/03/14 14:47:03 pgoyette Exp $ 2.\" 3.\" Copyright (c) 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Juan Romero Pardines. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 14, 2010 31.Dt ENVSYS 4 32.Os 33.Sh NAME 34.Nm envsys 35.Nd Environmental Systems framework (version 2) 36.Sh SYNOPSIS 37.In sys/envsys.h 38.Sh DESCRIPTION 39The 40.Nm 41framework provides support to handle hardware monitor devices. 42Hardware monitoring chips are able to report values from different types of 43sensors. 44.Pp 45The 46.Nm 47framework consists of two parts: 48.Pp 49.Bl -enum -offset indent -compact 50.It 51the userland part, to receive the current sensor data and 52to set some properties on sensors: 53.Xr envstat 8 . 54.It 55The kernel part that is able to talk to the drivers providing sensor 56data: 57.Xr sysmon_envsys 9 . 58.El 59.Pp 60The 61.Nm 62framework uses 63.Xr proplib 3 64for communication between kernel and user space. 65The following 66.Xr ioctl 2 67types are available: 68.Pp 69.Bl -tag -width XX 70.It Dv ENVSYS_GETDICTIONARY Pq prop_dictionary_t 71.Pp 72This 73.Xr ioctl 2 74is used to receive the global dictionary that is being used in 75the kernel by the 76.Xr sysmon_envsys 9 77framework. 78It will contain an array of dictionaries per device 79and one dictionary per sensor plus another special dictionary that 80contains the properties for a device. 81Each sensor dictionary will have their own characteristics and values. 82.Pp 83The following XML property list represents a virtual device 84.Dq device0 85with one sensor 86.Dq sensor0 87and all available properties set on it, plus another sensor for 88the 89.Dq device-properties 90dictionary (which contains specific properties for a device): 91.Pp 92.Bd -literal 93\&\*[Lt]key\&\*[Gt]device0\&\*[Lt]\&/key\&\*[Gt] 94\&\*[Lt]array\&\*[Gt] 95 \&\*[Lt]dict\&\*[Gt] 96 \&\*[Lt]key\&\*[Gt]allow-rfact\&\*[Lt]\&/key\&\*[Gt] 97 \&\*[Lt]true\&/\&\*[Gt] 98 \&\*[Lt]key\&\*[Gt]avg-value\&\*[Lt]\&/key\&\*[Gt] 99 \&\*[Lt]integer\&\*[Gt]36400\&\*[Lt]\&/integer\&\*[Gt] 100 \&\*[Lt]key\&\*[Gt]battery-capacity\&\*[Lt]\&/key\&\*[Gt] 101 \&\*[Lt]string\&\*[Gt]NORMAL\&\*[Lt]\&/string\&\*[Gt] 102 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 103 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 104 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 105 \&\*[Lt]integer\&\*[Gt]343150000\&\*[Lt]\&/integer\&\*[Gt] 106 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 107 \&\*[Lt]integer\&\*[Gt]288150000\&\*[Lt]\&/integer\&\*[Gt] 108 \&\*[Lt]key\&\*[Gt]cur-value\&\*[Lt]\&/key\&\*[Gt] 109 \&\*[Lt]integer\&\*[Gt]406000\&\*[Lt]\&/integer\&\*[Gt] 110 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 111 \&\*[Lt]string\&\*[Gt]CPU Temp\&\*[Lt]\&/string\&\*[Gt] 112 \&\*[Lt]key\&\*[Gt]high-capacity\&\*[Lt]\&/key\&\*[Gt] 113 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 114 \&\*[Lt]string\&\*[Gt]index\&\*[Lt]\&/string\&\*[Gt] 115 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 116 \&\*[Lt]key\&\*[Gt]max-value\&\*[Lt]\&/key\&\*[Gt] 117 \&\*[Lt]integer\&\*[Gt]3894000\&\*[Lt]\&/integer\&\*[Gt] 118 \&\*[Lt]key\&\*[Gt]maximum-capacity\&\*[Lt]\&/key\&\*[Gt] 119 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 120 \&\*[Lt]key\&\*[Gt]min-value\&\*[Lt]\&/key\&\*[Gt] 121 \&\*[Lt]integer\&\*[Gt]2894000\&\*[Lt]\&/integer\&\*[Gt] 122 \&\*[Lt]key\&\*[Gt]monitoring-state-critical\&\*[Lt]\&/key\&\*[Gt] 123 \&\*[Lt]true\&/\&\*[Gt] 124 \&\*[Lt]key\&\*[Gt]monitoring-state-critover\&\*[Lt]\&/key\&\*[Gt] 125 \&\*[Lt]true\&/\&\*[Gt] 126 \&\*[Lt]key\&\*[Gt]monitoring-state-critunder\&\*[Lt]\&/key\&\*[Gt] 127 \&\*[Lt]true\&/\&\*[Gt] 128 \&\*[Lt]key\&\*[Gt]monitoring-state-state-changed\&\*[Lt]\&/key\&\*[Gt] 129 \&\*[Lt]true\&/\&\*[Gt] 130 \&\*[Lt]key\&\*[Gt]monitoring-state-warnover\&\*[Lt]\&/key\&\*[Gt] 131 \&\*[Lt]true\&/\&\*[Gt] 132 \&\*[Lt]key\&\*[Gt]monitoring-state-warnunder\&\*[Lt]\&/key\&\*[Gt] 133 \&\*[Lt]true\&/\&\*[Gt] 134 \&\*[Lt]key\&\*[Gt]monitoring-supported\&\*[Lt]\&/key\&\*[Gt] 135 \&\*[Lt]true\&/\&\*[Gt] 136 \&\*[Lt]key\&\*[Gt]state\&\*[Lt]\&/key\&\*[Gt] 137 \&\*[Lt]string\&\*[Gt]valid\&\*[Lt]\&/string\&\*[Gt] 138 \&\*[Lt]key\&\*[Gt]type\&\*[Lt]\&/key\&\*[Gt] 139 \&\*[Lt]string\&\*[Gt]Ampere hour\&\*[Lt]\&/string\&\*[Gt] 140 \&\*[Lt]key\&\*[Gt]want-percentage\&\*[Lt]\&/key\&\*[Gt] 141 \&\*[Lt]true\&/\&\*[Gt] 142 \&\*[Lt]key\&\*[Gt]warning-capacity\&\*[Lt]\&/key\&\*[Gt] 143 \&\*[Lt]integer\&\*[Gt]19234\&\*[Lt]\&/integer\&\*[Gt] 144 \&\*[Lt]key\&\*[Gt]warning-max\&\*[Lt]\&/key\&\*[Gt] 145 \&\*[Lt]integer\&\*[Gt]323150000\&\*[Lt]\&/integer\&\*[Gt] 146 \&\*[Lt]key\&\*[Gt]warning-min\&\*[Lt]\&/key\&\*[Gt] 147 \&\*[Lt]integer\&\*[Gt]298150000\&\*[Lt]\&/integer\&\*[Gt] 148 \&\*[Lt]\&/dict\&\*[Gt] 149 \&\*[Lt]dict\&\*[Gt] 150 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 151 \&\*[Lt]dict\&\*[Gt] 152 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 153 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 154 \&\*[Lt]\&/dict\&\*[Gt] 155 \&\*[Lt]\&/dict\&\*[Gt] 156\&\*[Lt]\&/array\&\*[Gt] 157.Ed 158.Pp 159Let's explain some more about those objects: 160.Bl -tag -width "monitoring-state-critical-overxx" 161.It Fa allow-rfact 162Set to 163.Em true 164means that the sensor is able to change the resistor factor, 165only used in Voltage sensors. 166.It Fa avg-value 167Current average value in the sensor. 168.It Fa battery-capacity 169Current capacity state for a battery capacity sensor. 170.It Fa critical-capacity 171Critical capacity set previously by the 172.Dv ENVSYS_SETDICTIONARY 173.Xr ioctl 2 . 174Only available on sensors with the 175.Em want-percentage 176object enabled. 177.It Fa critical-max 178Critical max limit set previously by the 179.Dv ENVSYS_SETDICTIONARY 180.Xr ioctl 2 . 181.It Fa critical-min 182Critical min limit set previously by the 183.Dv ENVSYS_SETDICTIONARY 184.Xr ioctl 2 . 185.It Fa cur-value 186Current value in the sensor. 187.It Fa description 188Description of the sensor. 189.It Fa high-capacity 190High capacity set previously by the 191.Dv ENVSYS_SETDICTIONARY 192.Xr ioctl 2 . 193Only available on sensors with the 194.Em want-percentage 195object enabled. 196Used to monitor possible over-charging of batteries. 197.It Fa index 198Index position of the sensor. 199.It Fa max-value 200Current max value in the sensor. 201.It Fa maximum-capacity 202Maximum capacity set previously by the 203.Dv ENVSYS_SETDICTIONARY 204.Xr ioctl 2 . 205Only available on sensors with the 206.Em want-percentage 207object enabled. 208Used to monitor possible over-charging of batteries. 209.It Fa min-value 210Current min value in the sensor. 211.It Fa monitoring-state-critical 212If true, the driver has enabled the flag to monitor a critical state. 213.It Fa monitoring-state-hw-range-limits 214If true, the driver has enabled the flag to monitor warning or critical 215limits. 216.It Fa monitoring-state-state-changed 217If true, the driver has enabled the flag to monitor for state changes in 218a drive or Battery state sensor. 219.It Fa monitoring-supported 220If true, critical/warning capacity/max/min limits may be set by the 221.Dv ENVSYS_SETDICTIONARY 222.Xr ioctl 2 . 223.It Fa state 224Current state in the sensor. 225.It Fa type 226Type of unit in the sensor. 227.It Fa want-percentage 228If true, 229.Em max-value 230and 231.Em cur-value 232are valid and a percentage may be computed from them. 233.It Fa warning-capacity 234Warning capacity set previously by the 235.Dv ENVSYS_SETDICTIONARY 236.Xr ioctl 2 . 237Only available on sensors with the 238.Em want-percentage 239object enabled. 240.It Fa warning-max 241Warning max limit set previously by the 242.Dv ENVSYS_SETDICTIONARY 243.Xr ioctl 2 . 244.It Fa warning-min 245Warning min limit set previously by the 246.Dv ENVSYS_SETDICTIONARY 247.Xr ioctl 2 . 248.El 249.It Dv ENVSYS_REMOVEPROPS Pq prop_dictionary_t 250.Pp 251This 252.Xr ioctl 2 253is used to remove all properties that are currently set via the 254.Dv ENVSYS_SETDICTIONARY 255ioctl. 256The values will be set to defaults, the ones that the driver uses. 257.Pp 258Only one object is allowed on this dictionary: 259.Bd -literal -offset ident 260\*[Lt]key\*[Gt]envsys-remove-props\*[Lt]/key\*[Gt] 261\*[Lt]true/\*[Gt] 262.Ed 263.Pp 264It is a boolean object and must be set to 265.Em true 266to be effective. 267.It Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t 268This 269.Xr ioctl 2 270is used to send a dictionary with new properties that should be 271processed by the 272.Nm 273framework. 274Only a set of predefined keywords are recognized by the kernel part. 275The following is the property list representation 276of a dictionary with all recognized and required keywords that 277a sensor understands: 278.Bd -literal 279\&\*[Lt]dict\&\*[Gt] 280 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 281 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 282 \&\*[Lt]key\&\*[Gt]rfact\&\*[Lt]\&/key\&\*[Gt] 283 \&\*[Lt]integer\&\*[Gt]56000\&\*[Lt]\&/integer\&\*[Gt] 284 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 285 \&\*[Lt]integer\&\*[Gt]10\&\*[Lt]\&/integer\&\*[Gt] 286 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 287 \&\*[Lt]integer\&\*[Gt]3400\&\*[Lt]\&/integer\&\*[Gt] 288 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 289 \&\*[Lt]integer\&\*[Gt]2800\&\*[Lt]\&/integer\&\*[Gt] 290 \&\*[Lt]key\&\*[Gt]high-capacity\&\*[Lt]\&/key\&\*[Gt] 291 \&\*[Lt]integer\&\*[Gt]95\&\*[Lt]\&/integer\&\*[Gt] 292 \&\*[Lt]key\&\*[Gt]maximum-capacity\&\*[Lt]\&/key\&\*[Gt] 293 \&\*[Lt]integer\&\*[Gt]100\&\*[Lt]\&/integer\&\*[Gt] 294 \&\*[Lt]key\&\*[Gt]warning-capacity\&\*[Lt]\&/key\&\*[Gt] 295 \&\*[Lt]integer\&\*[Gt]15\&\*[Lt]\&/integer\&\*[Gt] 296 \&\*[Lt]key\&\*[Gt]warning-max\&\*[Lt]\&/key\&\*[Gt] 297 \&\*[Lt]integer\&\*[Gt]3200\&\*[Lt]\&/integer\&\*[Gt] 298 \&\*[Lt]key\&\*[Gt]warning-min\&\*[Lt]\&/key\&\*[Gt] 299 \&\*[Lt]integer\&\*[Gt]2900\&\*[Lt]\&/integer\&\*[Gt] 300\&\*[Lt]\&/dict\&\*[Gt] 301.Ed 302.Pp 303Also if some properties in a device need to be changed, the 304.Dq device-properties 305dictionary must be used. 306At this moment only the 307.Dq refresh-timeout 308property is understood. 309This has the following structure: 310.Bd -literal 311\&\*[Lt]dict\&\*[Gt] 312 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 313 \&\*[Lt]dict\&\*[Gt] 314 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 315 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 316 \&\*[Lt]\&/dict\&\*[Gt] 317\&\*[Lt]\&/dict\&\*[Gt] 318.Ed 319.Pp 320A dictionary sent to the kernel with this 321.Xr ioctl 2 322should have the following structure: 323.Bd -literal 324\&\*[Lt]dict\&\*[Gt] 325 \&\*[Lt]key\&\*[Gt]device_name\&\*[Lt]\&/key\&\*[Gt] 326 \&\*[Lt]array\&\*[Gt] 327 \&\*[Lt]dict\&\*[Gt] 328 \&\*[Lt]key\&\*[Gt]index\&\*[Lt]\&/key\&\*[Gt] 329 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 330 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 331 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 332 ... 333 Another property for this sensor 334 ... 335 \&\*[Lt]\&/dict\&\*[Gt] 336 ... 337 Another dictionary for device-properties or sensor 338 ... 339 \&\*[Lt]\&/array\&\*[Gt] 340 ... 341 Another device as above 342 ... 343\&\*[Lt]\&/dict\&\*[Gt] 344.Ed 345.Pp 346The named device will be an array and will contain dictionaries, 347any dictionary needs to have the 348.Em index 349object specifying the sensor that is required for the new properties. 350.Pp 351If an unknown object was sent with the dictionary, 352.Er EINVAL 353will be returned, or if the sensor does not support changing 354rfact (voltage sensors) or critical/warning/capacity limits, 355.Er ENOTSUP 356will be returned. 357.El 358.Sh NOTES 359When setting a critical/warning max or min limit with the 360.Dv ENVSYS_SETDICTIONARY 361.Xr ioctl 2 , 362the user must be aware that 363.Xr sysmon_envsys 9 364expects to have a proper unit, so the value must be converted. 365Please see 366.Xr sysmon_envsys 9 367for more information. 368.Pp 369Also when setting a critical or warning capacity limit, the formula to send a 370proper value to 371.Xr sysmon_envsys 9 372is the following: 373.Em value = (value / 100) * max value . 374The max value is available in the sensor's dictionary. 375.Sh EXAMPLES 376The following example shows how to change the description 377of 378.Ql sensor0 379in the 380.Ql aibs0 381device with the 382.Dv ENVSYS_SETDICTIONARY 383.Xr ioctl 2 : 384.Bd -literal 385int 386main(void) 387{ 388 prop_dictionary_t global_dict, sensor_dict; 389 prop_array_t array; 390 prop_object_t obj; 391 int fd, error; 392 393 global_dict = prop_dictionary_create(); 394 sensor_dict = prop_dictionary_create(); 395 array = prop_array_create(); 396 397 if (!prop_dictionary_set(global_dict, "aibs0", array)) 398 err(EINVAL, "prop_dictionary_set global"); 399 400 obj = prop_string_create_cstring_nocopy("sensor0"); 401 if (obj == NULL || 402 !prop_dictionary_set(sensor_dict, "index", obj)) 403 err(EINVAL, "sensor index"); 404 405 prop_object_release(obj); 406 407 /* new description */ 408 obj = prop_string_create_cstring_nocopy("CPU core voltage"); 409 if (obj == NULL || 410 !prop_dictionary_set(sensor_dict, "description", obj)) 411 err(EINVAL, "new description"); 412 413 prop_object_release(obj); 414 415 if (!prop_array_add(array, sensor_dict)) 416 err(EINVAL, "prop_array_add"); 417 418 if ((fd = open(_DEV_SYSMON, O_RDWR)) == \-1) 419 err(EXIT_FAILURE, "open"); 420 421 /* we are done, send the dictionary */ 422 error = prop_dictionary_send_ioctl(global_dict, 423 fd, 424 ENVSYS_SETDICTIONARY); 425 prop_object_release(array); 426 prop_object_release(global_dict); 427 (void)close(fd); 428 return error; 429} 430.Ed 431.Sh SEE ALSO 432.Xr envstat 8 , 433.Xr powerd 8 , 434.Xr sysmon_envsys 9 435.Sh HISTORY 436The first 437.Em envsys 438framework first appeared in 439.Nx 1.5 . 440The 441.Em envsys 2 442framework first appeared in 443.Nx 5.0 . 444.Sh AUTHORS 445The (current) 446.Em envsys 2 447framework was implemented by 448.An Juan Romero Pardines . 449Additional input on the design was provided by many 450.Nx 451developers around the world. 452.Pp 453The first 454.Em envsys 455framework was implemented by Jason R. Thorpe, Tim Rightnour, 456and Bill Squier. 457