1.\" $NetBSD: envsys.4,v 1.42 2009/03/15 12:33:53 joerg 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.It Dv ENVSYS_REMOVEPROPS Pq prop_dictionary_t 214.Pp 215This 216.Xr ioctl 2 217is used to remove all properties that are currently set via the 218.Dv ENVSYS_SETDICTIONARY 219ioctl. 220The values will be set to defaults, the ones that the driver uses. 221.Pp 222Only one object is allowed on this dictionary: 223.Bd -literal -offset -ident 224 \*[Lt]key\*[Gt]envsys-remove-props\*[Lt]/key\*[Gt] 225 \*[Lt]true/\*[Gt] 226.Ed 227.Pp 228It is a boolean object and must be set to 229.Em true 230to be effective. 231.It Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t 232This 233.Xr ioctl 2 234is used to send a dictionary with new properties that should be 235processed by the 236.Nm 237framework. 238Only a set of predefined keywords are recognized by the kernel part. 239The following is the property list representation 240of a dictionary with all recognized and required keywords that 241a sensor understands: 242.Bd -literal 243\&\*[Lt]dict\&\*[Gt] 244 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 245 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 246 \&\*[Lt]key\&\*[Gt]rfact\&\*[Lt]\&/key\&\*[Gt] 247 \&\*[Lt]integer\&\*[Gt]56000\&\*[Lt]\&/integer\&\*[Gt] 248 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 249 \&\*[Lt]integer\&\*[Gt]10\&\*[Lt]\&/integer\&\*[Gt] 250 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 251 \&\*[Lt]integer\&\*[Gt]3400\&\*[Lt]\&/integer\&\*[Gt] 252 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 253 \&\*[Lt]integer\&\*[Gt]2800\&\*[Lt]\&/integer\&\*[Gt] 254\&\*[Lt]\&/dict\&\*[Gt] 255.Ed 256.Pp 257Also if some properties in a device need to be changed, the 258.Dq device-properties 259dictionary must be used. 260At this moment only the 261.Dq refresh-timeout 262property is understood. 263This has the following structure: 264.Bd -literal 265\&\*[Lt]dict\&\*[Gt] 266 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 267 \&\*[Lt]dict\&\*[Gt] 268 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 269 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 270 \&\*[Lt]\&/dict\&\*[Gt] 271\&\*[Lt]\&/dict\&\*[Gt] 272.Ed 273.Pp 274A dictionary sent to the kernel with this 275.Xr ioctl 2 276should have the following structure: 277.Bd -literal 278\&\*[Lt]dict\&\*[Gt] 279 \&\*[Lt]key\&\*[Gt]device_name\&\*[Lt]\&/key\&\*[Gt] 280 \&\*[Lt]array\&\*[Gt] 281 \&\*[Lt]dict\&\*[Gt] 282 \&\*[Lt]key\&\*[Gt]index\&\*[Lt]\&/key\&\*[Gt] 283 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 284 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 285 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 286 ... 287 Another property for this sensor 288 ... 289 \&\*[Lt]\&/dict\&\*[Gt] 290 ... 291 Another dictionary for device-properties or sensor 292 ... 293 \&\*[Lt]\&/array\&\*[Gt] 294 ... 295 Another device as above 296 ... 297\&\*[Lt]\&/dict\&\*[Gt] 298.Ed 299.Pp 300The named device will be an array and will contain dictionaries, 301any dictionary needs to have the 302.Em index 303object specifying the sensor that is required for the new properties. 304.Pp 305If an unknown object was sent with the dictionary, 306.Er EINVAL 307will be returned, or if the sensor does not support changing 308rfact (voltage sensors) or critical/capacity limits, 309.Er ENOTSUP 310will be returned. 311.El 312.Sh NOTES 313When setting a critical max or min limit with the 314.Dv ENVSYS_SETDICTIONARY 315.Xr ioctl 2 , 316the user must be aware that 317.Xr sysmon_envsys 9 318expects to have a proper unit, so the value must be converted. 319Please see 320.Xr sysmon_envsys 9 321for more information. 322.Pp 323Also when setting a critical capacity limit, the formula to send a 324proper value to 325.Xr sysmon_envsys 9 326is the following: 327.Em value = (value / 100) * max value . 328The max value is available in the sensor's dictionary. 329.Sh EXAMPLES 330The following example shows how to change the description 331of 332.Ql sensor0 333in the 334.Ql aiboost0 335device with the 336.Dv ENVSYS_SETDICTIONARY 337.Xr ioctl 2 : 338.Bd -literal 339int 340main(void) 341{ 342 prop_dictionary_t global_dict, sensor_dict; 343 prop_array_t array; 344 prop_object_t obj; 345 int fd; 346 347 global_dict = prop_dictionary_create(); 348 sensor_dict = prop_dictionary_create(); 349 array = prop_array_create(); 350 351 if (!prop_dictionary_set(global_dict, "aiboost0", array)) 352 err(EINVAL, "prop_dictionary_set global"); 353 354 obj = prop_string_create_cstring_nocopy("sensor0"); 355 if (obj == NULL || 356 !prop_dictionary_set(dict, "index", obj)) 357 err(EINVAL, "sensor index"); 358 359 prop_object_release(obj); 360 361 /* new description */ 362 obj = prop_string_create_cstring_nocopy("CPU temp"); 363 if (obj == NULL || 364 !prop_dictionary_set(dict, "description", obj)) 365 err(EINVAL, "new description"); 366 367 prop_object_release(obj); 368 369 if (!prop_array_add(array, sensor_dict)) 370 err(EINVAL, "prop_array_add"); 371 372 if ((fd = open(_DEV_SYSMON, O_RDWR)) == \-1) 373 err(EXIT_FAILURE, "open") 374 375 /* we are done, send the dictionary */ 376 error = prop_dictionary_send_ioctl(global_dict, 377 fd, 378 ENVSYS_SETDICTIONARY); 379 prop_object_release(array); 380 prop_object_release(global_dict); 381 (void)close(fd); 382 return error; 383} 384.Ed 385.Sh SEE ALSO 386.Xr envstat 8 , 387.Xr powerd 8 , 388.Xr sysmon_envsys 9 389.Sh HISTORY 390The first 391.Em envsys 392framework first appeared in 393.Nx 1.5 . 394The 395.Em envsys 2 396framework first appeared in 397.Nx 5.0 . 398.Sh AUTHORS 399The (current) 400.Em envsys 2 401framework was implemented by 402.An Juan Romero Pardines . 403Additional input on the design was provided by many 404.Nx 405developers around the world. 406.Pp 407The first 408.Em envsys 409framework was implemented by Jason R. Thorpe, Tim Rightnour, 410and Bill Squier. 411