1.\" $NetBSD: envsys.4,v 1.50 2013/01/12 03:16:43 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 January 10, 2013 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 devices 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 its own characteristics and values. 82.Pp 83The following XML property list represents a virtual device 84.Dq device0 85with one entry for sensor 86.Dq sensor0 87and all available properties set on it, plus another entry for the 88.Dq device-properties 89dictionary (which contains specific properties for a device): 90.Pp 91.Bd -literal 92\&\*[Lt]key\&\*[Gt]device0\&\*[Lt]\&/key\&\*[Gt] 93\&\*[Lt]array\&\*[Gt] 94 \&\*[Lt]dict\&\*[Gt] 95 \&\*[Lt]key\&\*[Gt]allow-rfact\&\*[Lt]\&/key\&\*[Gt] 96 \&\*[Lt]true\&/\&\*[Gt] 97 \&\*[Lt]key\&\*[Gt]avg-value\&\*[Lt]\&/key\&\*[Gt] 98 \&\*[Lt]integer\&\*[Gt]36400\&\*[Lt]\&/integer\&\*[Gt] 99 \&\*[Lt]key\&\*[Gt]battery-capacity\&\*[Lt]\&/key\&\*[Gt] 100 \&\*[Lt]string\&\*[Gt]NORMAL\&\*[Lt]\&/string\&\*[Gt] 101 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 102 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 103 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 104 \&\*[Lt]integer\&\*[Gt]343150000\&\*[Lt]\&/integer\&\*[Gt] 105 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 106 \&\*[Lt]integer\&\*[Gt]288150000\&\*[Lt]\&/integer\&\*[Gt] 107 \&\*[Lt]key\&\*[Gt]cur-value\&\*[Lt]\&/key\&\*[Gt] 108 \&\*[Lt]integer\&\*[Gt]406000\&\*[Lt]\&/integer\&\*[Gt] 109 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 110 \&\*[Lt]string\&\*[Gt]CPU Temp\&\*[Lt]\&/string\&\*[Gt] 111 \&\*[Lt]key\&\*[Gt]high-capacity\&\*[Lt]\&/key\&\*[Gt] 112 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 113 \&\*[Lt]string\&\*[Gt]index\&\*[Lt]\&/string\&\*[Gt] 114 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 115 \&\*[Lt]key\&\*[Gt]max-value\&\*[Lt]\&/key\&\*[Gt] 116 \&\*[Lt]integer\&\*[Gt]3894000\&\*[Lt]\&/integer\&\*[Gt] 117 \&\*[Lt]key\&\*[Gt]maximum-capacity\&\*[Lt]\&/key\&\*[Gt] 118 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 119 \&\*[Lt]key\&\*[Gt]min-value\&\*[Lt]\&/key\&\*[Gt] 120 \&\*[Lt]integer\&\*[Gt]2894000\&\*[Lt]\&/integer\&\*[Gt] 121 \&\*[Lt]key\&\*[Gt]monitoring-state-critical\&\*[Lt]\&/key\&\*[Gt] 122 \&\*[Lt]true\&/\&\*[Gt] 123 \&\*[Lt]key\&\*[Gt]monitoring-state-critover\&\*[Lt]\&/key\&\*[Gt] 124 \&\*[Lt]true\&/\&\*[Gt] 125 \&\*[Lt]key\&\*[Gt]monitoring-state-critunder\&\*[Lt]\&/key\&\*[Gt] 126 \&\*[Lt]true\&/\&\*[Gt] 127 \&\*[Lt]key\&\*[Gt]monitoring-state-state-changed\&\*[Lt]\&/key\&\*[Gt] 128 \&\*[Lt]true\&/\&\*[Gt] 129 \&\*[Lt]key\&\*[Gt]monitoring-state-warnover\&\*[Lt]\&/key\&\*[Gt] 130 \&\*[Lt]true\&/\&\*[Gt] 131 \&\*[Lt]key\&\*[Gt]monitoring-state-warnunder\&\*[Lt]\&/key\&\*[Gt] 132 \&\*[Lt]true\&/\&\*[Gt] 133 \&\*[Lt]key\&\*[Gt]monitoring-supported\&\*[Lt]\&/key\&\*[Gt] 134 \&\*[Lt]true\&/\&\*[Gt] 135 \&\*[Lt]key\&\*[Gt]state\&\*[Lt]\&/key\&\*[Gt] 136 \&\*[Lt]string\&\*[Gt]valid\&\*[Lt]\&/string\&\*[Gt] 137 \&\*[Lt]key\&\*[Gt]type\&\*[Lt]\&/key\&\*[Gt] 138 \&\*[Lt]string\&\*[Gt]Ampere hour\&\*[Lt]\&/string\&\*[Gt] 139 \&\*[Lt]key\&\*[Gt]want-percentage\&\*[Lt]\&/key\&\*[Gt] 140 \&\*[Lt]true\&/\&\*[Gt] 141 \&\*[Lt]key\&\*[Gt]warning-capacity\&\*[Lt]\&/key\&\*[Gt] 142 \&\*[Lt]integer\&\*[Gt]19234\&\*[Lt]\&/integer\&\*[Gt] 143 \&\*[Lt]key\&\*[Gt]warning-max\&\*[Lt]\&/key\&\*[Gt] 144 \&\*[Lt]integer\&\*[Gt]323150000\&\*[Lt]\&/integer\&\*[Gt] 145 \&\*[Lt]key\&\*[Gt]warning-min\&\*[Lt]\&/key\&\*[Gt] 146 \&\*[Lt]integer\&\*[Gt]298150000\&\*[Lt]\&/integer\&\*[Gt] 147 \&\*[Lt]\&/dict\&\*[Gt] 148 \&\*[Lt]dict\&\*[Gt] 149 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 150 \&\*[Lt]dict\&\*[Gt] 151 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 152 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 153 \&\*[Lt]\&/dict\&\*[Gt] 154 \&\*[Lt]\&/dict\&\*[Gt] 155\&\*[Lt]\&/array\&\*[Gt] 156.Ed 157.Pp 158Let's explain some more about those objects: 159.Bl -tag -width "monitoring-state-critical-overxx" 160.It Fa allow-rfact 161Set to 162.Em true 163means that the sensor is able to change the resistor factor, 164only used in Voltage sensors. 165.It Fa avg-value 166Current average value in the sensor. 167.It Fa battery-capacity 168Current capacity state for a battery capacity sensor. 169.It Fa critical-capacity 170Critical capacity set previously by the 171.Dv ENVSYS_SETDICTIONARY 172.Xr ioctl 2 . 173Only available on sensors with the 174.Em want-percentage 175object enabled. 176.It Fa critical-max 177Critical max limit set previously by the 178.Dv ENVSYS_SETDICTIONARY 179.Xr ioctl 2 . 180.It Fa critical-min 181Critical min limit set previously by the 182.Dv ENVSYS_SETDICTIONARY 183.Xr ioctl 2 . 184.It Fa cur-value 185Current value in the sensor. 186.It Fa description 187Description of the sensor. 188.It Fa high-capacity 189High capacity set previously by the 190.Dv ENVSYS_SETDICTIONARY 191.Xr ioctl 2 . 192Only available on sensors with the 193.Em want-percentage 194object enabled. 195Used to monitor possible over-charging of batteries. 196.It Fa index 197Index position of the sensor. 198.It Fa max-value 199Current max value in the sensor. 200.It Fa maximum-capacity 201Maximum capacity set previously by the 202.Dv ENVSYS_SETDICTIONARY 203.Xr ioctl 2 . 204Only available on sensors with the 205.Em want-percentage 206object enabled. 207Used to monitor possible over-charging of batteries. 208.It Fa min-value 209Current min value in the sensor. 210.It Fa monitoring-state-critical 211If true, the device has enabled the flag to monitor a critical state. 212.It Fa monitoring-state-hw-range-limits 213If true, the device has enabled the flag to monitor warning or critical 214limits. 215.It Fa monitoring-state-state-changed 216If true, the device has enabled the flag to monitor for state changes in 217a drive or Battery state sensor. 218.It Fa monitoring-supported 219If true, critical/warning capacity/max/min limits may be set by the 220.Dv ENVSYS_SETDICTIONARY 221.Xr ioctl 2 . 222.It Fa state 223Current state in the sensor. 224.It Fa type 225Type of unit in the sensor. 226.It Fa want-percentage 227If true, 228.Em max-value 229and 230.Em cur-value 231are valid and a percentage may be computed from them. 232.It Fa warning-capacity 233Warning capacity set previously by the 234.Dv ENVSYS_SETDICTIONARY 235.Xr ioctl 2 . 236Only available on sensors with the 237.Em want-percentage 238object enabled. 239.It Fa warning-max 240Warning max limit set previously by the 241.Dv ENVSYS_SETDICTIONARY 242.Xr ioctl 2 . 243.It Fa warning-min 244Warning min limit set previously by the 245.Dv ENVSYS_SETDICTIONARY 246.Xr ioctl 2 . 247.El 248.It Dv ENVSYS_REMOVEPROPS Pq prop_dictionary_t 249.Pp 250This 251.Xr ioctl 2 252is used to remove all properties that are currently set via the 253.Dv ENVSYS_SETDICTIONARY 254ioctl. 255The values will be set to defaults, the ones that the device uses. 256.Pp 257Only one object is allowed on this dictionary: 258.Bd -literal -offset ident 259\*[Lt]key\*[Gt]envsys-remove-props\*[Lt]/key\*[Gt] 260\*[Lt]true/\*[Gt] 261.Ed 262.Pp 263It is a boolean object and must be set to 264.Em true 265to be effective. 266.It Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t 267This 268.Xr ioctl 2 269is used to send a dictionary with new properties that should be 270processed by the 271.Nm 272framework. 273Only a set of predefined keywords are recognized by the kernel part. 274The following is the property list representation 275of a dictionary with all recognized and required keywords that 276a sensor understands: 277.Bd -literal 278\&\*[Lt]dict\&\*[Gt] 279 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 280 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 281 \&\*[Lt]key\&\*[Gt]rfact\&\*[Lt]\&/key\&\*[Gt] 282 \&\*[Lt]integer\&\*[Gt]56000\&\*[Lt]\&/integer\&\*[Gt] 283 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 284 \&\*[Lt]integer\&\*[Gt]10\&\*[Lt]\&/integer\&\*[Gt] 285 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 286 \&\*[Lt]integer\&\*[Gt]3400\&\*[Lt]\&/integer\&\*[Gt] 287 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 288 \&\*[Lt]integer\&\*[Gt]2800\&\*[Lt]\&/integer\&\*[Gt] 289 \&\*[Lt]key\&\*[Gt]high-capacity\&\*[Lt]\&/key\&\*[Gt] 290 \&\*[Lt]integer\&\*[Gt]95\&\*[Lt]\&/integer\&\*[Gt] 291 \&\*[Lt]key\&\*[Gt]maximum-capacity\&\*[Lt]\&/key\&\*[Gt] 292 \&\*[Lt]integer\&\*[Gt]100\&\*[Lt]\&/integer\&\*[Gt] 293 \&\*[Lt]key\&\*[Gt]warning-capacity\&\*[Lt]\&/key\&\*[Gt] 294 \&\*[Lt]integer\&\*[Gt]15\&\*[Lt]\&/integer\&\*[Gt] 295 \&\*[Lt]key\&\*[Gt]warning-max\&\*[Lt]\&/key\&\*[Gt] 296 \&\*[Lt]integer\&\*[Gt]3200\&\*[Lt]\&/integer\&\*[Gt] 297 \&\*[Lt]key\&\*[Gt]warning-min\&\*[Lt]\&/key\&\*[Gt] 298 \&\*[Lt]integer\&\*[Gt]2900\&\*[Lt]\&/integer\&\*[Gt] 299\&\*[Lt]\&/dict\&\*[Gt] 300.Ed 301.Pp 302Also if some properties in a device need to be changed, the 303.Dq device-properties 304dictionary must be used. 305At this moment only the 306.Dq refresh-timeout 307property is understood. 308This has the following structure: 309.Bd -literal 310\&\*[Lt]dict\&\*[Gt] 311 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 312 \&\*[Lt]dict\&\*[Gt] 313 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 314 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 315 \&\*[Lt]\&/dict\&\*[Gt] 316\&\*[Lt]\&/dict\&\*[Gt] 317.Ed 318.Pp 319A dictionary sent to the kernel with this 320.Xr ioctl 2 321should have the following structure: 322.Bd -literal 323\&\*[Lt]dict\&\*[Gt] 324 \&\*[Lt]key\&\*[Gt]device_name\&\*[Lt]\&/key\&\*[Gt] 325 \&\*[Lt]array\&\*[Gt] 326 \&\*[Lt]dict\&\*[Gt] 327 \&\*[Lt]key\&\*[Gt]index\&\*[Lt]\&/key\&\*[Gt] 328 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 329 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 330 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 331 ... 332 Another property for this sensor 333 ... 334 \&\*[Lt]\&/dict\&\*[Gt] 335 ... 336 Another dictionary for device-properties or sensor 337 ... 338 \&\*[Lt]\&/array\&\*[Gt] 339 ... 340 Another device as above 341 ... 342\&\*[Lt]\&/dict\&\*[Gt] 343.Ed 344.Pp 345The named device will be an array and will contain dictionaries, 346any dictionary needs to have the 347.Em index 348object specifying the sensor that is required for the new properties. 349.Pp 350If an unknown object was sent with the dictionary, 351.Er EINVAL 352will be returned, or if the sensor does not support changing 353rfact (voltage sensors) or critical/warning/capacity limits, 354.Er ENOTSUP 355will be returned. 356.El 357.Sh NOTES 358When setting a critical/warning max or min limit with the 359.Dv ENVSYS_SETDICTIONARY 360.Xr ioctl 2 , 361the user must be aware that 362.Xr sysmon_envsys 9 363expects to have a proper unit, so the value must be converted. 364Please see 365.Xr sysmon_envsys 9 366for more information. 367.Pp 368Also when setting a critical or warning capacity limit, the formula to send a 369proper value to 370.Xr sysmon_envsys 9 371is the following: 372.Em value = (value / 100) * max value . 373The max value is available in the sensor's dictionary. 374.Sh EXAMPLES 375The following example shows how to change the description 376of 377.Ql sensor0 378in the 379.Ql aibs0 380device with the 381.Dv ENVSYS_SETDICTIONARY 382.Xr ioctl 2 : 383.Bd -literal 384int 385main(void) 386{ 387 prop_dictionary_t global_dict, sensor_dict; 388 prop_array_t array; 389 prop_object_t obj; 390 int fd, error; 391 392 global_dict = prop_dictionary_create(); 393 sensor_dict = prop_dictionary_create(); 394 array = prop_array_create(); 395 396 if (!prop_dictionary_set(global_dict, "aibs0", array)) 397 err(EINVAL, "prop_dictionary_set global"); 398 399 obj = prop_string_create_cstring_nocopy("sensor0"); 400 if (obj == NULL || 401 !prop_dictionary_set(sensor_dict, "index", obj)) 402 err(EINVAL, "sensor index"); 403 404 prop_object_release(obj); 405 406 /* new description */ 407 obj = prop_string_create_cstring_nocopy("CPU core voltage"); 408 if (obj == NULL || 409 !prop_dictionary_set(sensor_dict, "description", obj)) 410 err(EINVAL, "new description"); 411 412 prop_object_release(obj); 413 414 if (!prop_array_add(array, sensor_dict)) 415 err(EINVAL, "prop_array_add"); 416 417 if ((fd = open(_DEV_SYSMON, O_RDWR)) == \-1) 418 err(EXIT_FAILURE, "open"); 419 420 /* we are done, send the dictionary */ 421 error = prop_dictionary_send_ioctl(global_dict, 422 fd, 423 ENVSYS_SETDICTIONARY); 424 prop_object_release(array); 425 prop_object_release(global_dict); 426 (void)close(fd); 427 return error; 428} 429.Ed 430.Sh SEE ALSO 431.Xr envsys.conf 5 , 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