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