1.\" $NetBSD: envsys.4,v 1.55 2021/05/04 17:51:55 christos 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 May 4, 2021 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.Pp 356Additionally, the following 357.Xr ioctl 2 358commands are provided for compatibility purposes 359for applications written against the original experimental 360.Nm 361API available between 362.Nx 1.5 363and 364.Nx 4.0 ; 365they have been deprecated since 366.Nx 5.0 , 367and may be removed at any time: 368.Bl -tag -width Ds 369.It Dv ENVSYS_GTREDATA Pq envsys_tre_data_t 370.It Dv ENVSYS_GTREINFO Pq envsys_basic_info_t 371.El 372.Sh NOTES 373When setting a critical/warning max or min limit with the 374.Dv ENVSYS_SETDICTIONARY 375.Xr ioctl 2 , 376the user must be aware that 377.Xr sysmon_envsys 9 378expects to have a proper unit, so the value must be converted. 379Please see 380.Xr sysmon_envsys 9 381for more information. 382.Pp 383Also when setting a critical or warning capacity limit, the formula to send a 384proper value to 385.Xr sysmon_envsys 9 386is the following: 387.Em value = (value / 100) * max value . 388The max value is available in the sensor's dictionary. 389.Sh EXAMPLES 390The following example shows how to change the description 391of 392.Ql sensor0 393in the 394.Ql aibs0 395device with the 396.Dv ENVSYS_SETDICTIONARY 397.Xr ioctl 2 : 398.Bd -literal 399int 400main(void) 401{ 402 prop_dictionary_t global_dict, sensor_dict; 403 prop_array_t array; 404 prop_object_t obj; 405 int fd, error; 406 407 global_dict = prop_dictionary_create(); 408 sensor_dict = prop_dictionary_create(); 409 array = prop_array_create(); 410 411 if (!prop_dictionary_set(global_dict, "aibs0", array)) 412 err(EINVAL, "prop_dictionary_set global"); 413 414 obj = prop_string_create_nocopy("sensor0"); 415 if (obj == NULL || 416 !prop_dictionary_set(sensor_dict, "index", obj)) 417 err(EINVAL, "sensor index"); 418 419 prop_object_release(obj); 420 421 /* new description */ 422 obj = prop_string_create_cstring_nocopy("CPU core voltage"); 423 if (obj == NULL || 424 !prop_dictionary_set(sensor_dict, "description", obj)) 425 err(EINVAL, "new description"); 426 427 prop_object_release(obj); 428 429 if (!prop_array_add(array, sensor_dict)) 430 err(EINVAL, "prop_array_add"); 431 432 if ((fd = open(_PATH_SYSMON, O_RDWR)) == \-1) 433 err(EXIT_FAILURE, "open"); 434 435 /* we are done, send the dictionary */ 436 error = prop_dictionary_send_ioctl(global_dict, 437 fd, 438 ENVSYS_SETDICTIONARY); 439 prop_object_release(array); 440 prop_object_release(sensor_dict); 441 prop_object_release(global_dict); 442 (void)close(fd); 443 return error; 444} 445.Ed 446.Sh SEE ALSO 447.Xr envsys.conf 5 , 448.Xr envstat 8 , 449.Xr powerd 8 , 450.Xr sysmon_envsys 9 451.Sh HISTORY 452The first 453.Em envsys 454framework first appeared in 455.Nx 1.5 . 456The 457.Em envsys 2 458framework first appeared in 459.Nx 5.0 . 460.Sh AUTHORS 461The (current) 462.Em envsys 2 463framework was implemented by 464.An Juan Romero Pardines . 465Additional input on the design was provided by many 466.Nx 467developers around the world. 468.Pp 469The first 470.Em envsys 471framework was implemented by Jason R. Thorpe, Tim Rightnour, 472and Bill Squier. 473