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