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