1.\" $NetBSD: envsys.4,v 1.39 2007/12/02 19:54:32 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd November 13, 2007 38.Dt ENVSYS 4 39.Os 40.Sh NAME 41.Nm envsys 42.Nd Environmental Systems framework (version 2) 43.Sh SYNOPSIS 44.In sys/envsys.h 45.Sh DESCRIPTION 46The 47.Nm 48framework provides support to handle hardware monitor devices. 49Hardware monitoring chips are able to report values from different types of 50sensors. 51.Pp 52The 53.Nm 54framework consists of two parts: 55.Pp 56.Bl -enum -offset indent -compact 57.It 58the userland part, to receive the current sensor data and 59to set some properties on sensors: 60.Xr envstat 8 . 61.It 62The kernel part that is able to talk to the drivers providing sensor 63data: 64.Xr sysmon_envsys 9 . 65.El 66.Pp 67The 68.Nm 69framework uses 70.Xr proplib 3 71for communication between kernel and user space. 72The following 73.Xr ioctl 2 74types are available: 75.Pp 76.Bl -tag -width XX -compact 77.It Dv ENVSYS_GETDICTIONARY Pq prop_dictionary_t 78.Pp 79This 80.Xr ioctl 2 81is used to receive the global dictionary that is being used in 82the kernel by the 83.Xr sysmon_envsys 9 84framework. 85It will contain an array of dictionaries per device 86and one dictionary per sensor plus another special dictionary that 87contains the properties for a device. 88Each sensor dictionary will have their own characteristics and values. 89.Pp 90The following XML property list represents a virtual device 91.Dq device0 92with one sensor 93.Dq sensor0 94and all available properties set on it, plus another sensor for 95the 96.Dq device-properties 97dictionary (which contains specific properties for a device): 98.Pp 99.Bd -literal 100\&\*[Lt]key\&\*[Gt]device0\&\*[Lt]\&/key\&\*[Gt] 101\&\*[Lt]array\&\*[Gt] 102 \&\*[Lt]dict\&\*[Gt] 103 \&\*[Lt]key\&\*[Gt]allow-rfact\&\*[Lt]\&/key\&\*[Gt] 104 \&\*[Lt]true\&/\&\*[Gt] 105 \&\*[Lt]key\&\*[Gt]avg-value\&\*[Lt]\&/key\&\*[Gt] 106 \&\*[Lt]integer\&\*[Gt]36400\&\*[Lt]\&/integer\&\*[Gt] 107 \&\*[Lt]key\&\*[Gt]battery-capacity\&\*[Lt]\&/key\&\*[Gt] 108 \&\*[Lt]string\&\*[Gt]NORMAL\&\*[Lt]\&/string\&\*[Gt] 109 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 110 \&\*[Lt]integer\&\*[Gt]21417\&\*[Lt]\&/integer\&\*[Gt] 111 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 112 \&\*[Lt]integer\&\*[Gt]343150000\&\*[Lt]\&/integer\&\*[Gt] 113 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 114 \&\*[Lt]integer\&\*[Gt]288150000\&\*[Lt]\&/integer\&\*[Gt] 115 \&\*[Lt]key\&\*[Gt]cur-value\&\*[Lt]\&/key\&\*[Gt] 116 \&\*[Lt]integer\&\*[Gt]406000\&\*[Lt]\&/integer\&\*[Gt] 117 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 118 \&\*[Lt]string\&\*[Gt]CPU Temp\&\*[Lt]\&/string\&\*[Gt] 119 \&\*[Lt]string\&\*[Gt]index\&\*[Lt]\&/string\&\*[Gt] 120 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 121 \&\*[Lt]key\&\*[Gt]max-value\&\*[Lt]\&/key\&\*[Gt] 122 \&\*[Lt]integer\&\*[Gt]3894000\&\*[Lt]\&/integer\&\*[Gt] 123 \&\*[Lt]key\&\*[Gt]min-value\&\*[Lt]\&/key\&\*[Gt] 124 \&\*[Lt]integer\&\*[Gt]2894000\&\*[Lt]\&/integer\&\*[Gt] 125 \&\*[Lt]key\&\*[Gt]monitoring-state-critical\&\*[Lt]\&/key\&\*[Gt] 126 \&\*[Lt]true\&/\&\*[Gt] 127 \&\*[Lt]key\&\*[Gt]monitoring-state-critover\&\*[Lt]\&/key\&\*[Gt] 128 \&\*[Lt]true\&/\&\*[Gt] 129 \&\*[Lt]key\&\*[Gt]monitoring-state-critunder\&\*[Lt]\&/key\&\*[Gt] 130 \&\*[Lt]true\&/\&\*[Gt] 131 \&\*[Lt]key\&\*[Gt]monitoring-state-state-changed\&\*[Lt]\&/key\&\*[Gt] 132 \&\*[Lt]true\&/\&\*[Gt] 133 \&\*[Lt]key\&\*[Gt]monitoring-state-warnover\&\*[Lt]\&/key\&\*[Gt] 134 \&\*[Lt]true\&/\&\*[Gt] 135 \&\*[Lt]key\&\*[Gt]monitoring-state-warnunder\&\*[Lt]\&/key\&\*[Gt] 136 \&\*[Lt]true\&/\&\*[Gt] 137 \&\*[Lt]key\&\*[Gt]monitoring-supported\&\*[Lt]\&/key\&\*[Gt] 138 \&\*[Lt]true\&/\&\*[Gt] 139 \&\*[Lt]key\&\*[Gt]state\&\*[Lt]\&/key\&\*[Gt] 140 \&\*[Lt]string\&\*[Gt]valid\&\*[Lt]\&/string\&\*[Gt] 141 \&\*[Lt]key\&\*[Gt]type\&\*[Lt]\&/key\&\*[Gt] 142 \&\*[Lt]string\&\*[Gt]Ampere hour\&\*[Lt]\&/string\&\*[Gt] 143 \&\*[Lt]key\&\*[Gt]want-percentage\&\*[Lt]\&/key\&\*[Gt] 144 \&\*[Lt]true\&/\&\*[Gt] 145 \&\*[Lt]\&/dict\&\*[Gt] 146 \&\*[Lt]dict\&\*[Gt] 147 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 148 \&\*[Lt]dict\&\*[Gt] 149 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 150 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 151 \&\*[Lt]\&/dict\&\*[Gt] 152 \&\*[Lt]\&/dict\&\*[Gt] 153\&\*[Lt]\&/array\&\*[Gt] 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 161mean 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 index 187Index position of the sensor. 188.It Fa max-value 189Current max value in the sensor. 190.It Fa min-value 191Current min value in the sensor. 192.It Fa monitoring-state-critical 193If true, the driver has enabled the flag to monitor a critical state. 194.It Fa monitoring-state-critical-over 195If true, the driver has enabled the flag to monitor a critical over state. 196.It Fa monitoring-state-critical-under 197If true, the driver has enabled the flag to monitor a critical under state. 198.It Fa monitoring-state-state-changed 199If true, the driver has enabled the flag to monitor for state changes in 200a drive or Battery state sensor. 201.It Fa monitoring-state-warning-over 202If true, the driver has enabled the flag to monitor a warning over state. 203.It Fa monitoring-state-warning-under 204If true, the driver has enabled the flag to monitor a warning under state. 205.It Fa monitoring-supported 206If true, critical capacity/max/min limits may be set by the 207.Dv ENVSYS_SETDICTIONARY 208.Xr ioctl 2 . 209.It Fa state 210Current state in the sensor. 211.It Fa type 212Type of unit in the sensor. 213.It Fa want-percentage 214If true, 215.Em max-value 216and 217.Em cur-value 218are valid and a percentage may be computed from them. 219.El 220.El 221.Pp 222.Bl -tag -width XX -compact 223.It Dv ENVSYS_REMOVEPROPS Pq prop_dictionary_t 224.Pp 225This 226.Xr ioctl 2 227is used to remove all properties that are currently set via the 228.Dv ENVSYS_SETDICTIONARY 229ioctl. 230The values will be set to defaults, the ones that the driver uses. 231.Pp 232Only one object is allowed on this dictionary: 233.Bd -literal -offset -ident 234 \*[Lt]key\*[Gt]envsys-remove-props\*[Lt]/key\*[Gt] 235 \*[Lt]true/\*[Gt] 236.Ed 237.Pp 238It is a boolean object and must be set to 239.Em true 240to be effective. 241.El 242.Bl -tag -width XX -compact 243.Pp 244.It Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t 245.Pp 246This 247.Xr ioctl 2 248is used to send a dictionary with new properties that should be 249processed by the 250.Nm 251framework. 252Only a set of predefined keywords are recognized by the kernel part. 253The following is the property list representation 254of a dictionary with all recognized and required keywords that 255a sensor understands: 256.Bd -literal 257\&\*[Lt]dict\&\*[Gt] 258 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 259 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 260 \&\*[Lt]key\&\*[Gt]rfact\&\*[Lt]\&/key\&\*[Gt] 261 \&\*[Lt]integer\&\*[Gt]56000\&\*[Lt]\&/integer\&\*[Gt] 262 \&\*[Lt]key\&\*[Gt]critical-capacity\&\*[Lt]\&/key\&\*[Gt] 263 \&\*[Lt]integer\&\*[Gt]10\&\*[Lt]\&/integer\&\*[Gt] 264 \&\*[Lt]key\&\*[Gt]critical-max\&\*[Lt]\&/key\&\*[Gt] 265 \&\*[Lt]integer\&\*[Gt]3400\&\*[Lt]\&/integer\&\*[Gt] 266 \&\*[Lt]key\&\*[Gt]critical-min\&\*[Lt]\&/key\&\*[Gt] 267 \&\*[Lt]integer\&\*[Gt]2800\&\*[Lt]\&/integer\&\*[Gt] 268\&\*[Lt]\&/dict\&\*[Gt] 269.Ed 270.Pp 271Also if some properties in a device need to be changed, the 272.Dq device-properties 273dictionary must be used. 274At this moment only the 275.Dq refresh-timeout 276property is understood. 277This has the following structure: 278.Bd -literal 279\&\*[Lt]dict\&\*[Gt] 280 \&\*[Lt]key\&\*[Gt]device-properties\&\*[Lt]\&/key\&\*[Gt] 281 \&\*[Lt]dict\&\*[Gt] 282 \&\*[Lt]key\&\*[Gt]refresh-timeout\&\*[Lt]\&/key\&\*[Gt] 283 \&\*[Lt]integer\&\*[Gt]0xa\&\*[Lt]\&/integer\&\*[Gt] 284 \&\*[Lt]\&/dict\&\*[Gt] 285\&\*[Lt]\&/dict\&\*[Gt] 286.Ed 287.Pp 288A dictionary sent to the kernel with this 289.Xr ioctl 2 290should have the following structure: 291.Bd -literal 292\&\*[Lt]dict\&\*[Gt] 293 \&\*[Lt]key\&\*[Gt]device_name\&\*[Lt]\&/key\&\*[Gt] 294 \&\*[Lt]array\&\*[Gt] 295 \&\*[Lt]dict\&\*[Gt] 296 \&\*[Lt]key\&\*[Gt]index\&\*[Lt]\&/key\&\*[Gt] 297 \&\*[Lt]string\&\*[Gt]sensor0\&\*[Lt]\&/string\&\*[Gt] 298 \&\*[Lt]key\&\*[Gt]description\&\*[Lt]\&/key\&\*[Gt] 299 \&\*[Lt]string\&\*[Gt]cpu temp\&\*[Lt]\&/string\&\*[Gt] 300 ... 301 Another property for this sensor 302 ... 303 \&\*[Lt]\&/dict\&\*[Gt] 304 ... 305 Another dictionary for device-properties or sensor 306 ... 307 \&\*[Lt]\&/array\&\*[Gt] 308 ... 309 Another device as above 310 ... 311\&\*[Lt]\&/dict\&\*[Gt] 312.Ed 313.Pp 314The named device will be an array and will contain dictionaries, 315any dictionary needs to have the 316.Em index 317object specifying the sensor that is required for the new properties. 318.Pp 319If an unknown object was sent with the dictionary, 320.Er EINVAL 321will be returned, or if the sensor does not support changing 322rfact (voltage sensors) or critical/capacity limits, 323.Er ENOTSUP 324will be returned. 325.El 326.Sh NOTES 327When setting a critical max or min limit with the 328.Dv ENVSYS_SETDICTIONARY 329.Xr ioctl 2 , 330the user must be aware that 331.Xr sysmon_envsys 9 332expects to have a proper unit, so the value must be converted. 333Please see 334.Xr sysmon_envsys 9 335for more information. 336.Pp 337Also when setting a critical capacity limit, the formula to send a 338proper value to 339.Xr sysmon_envsys 9 340is the following: 341.Em value = (value / 100) * max value . 342The max value is available in the sensor's dictionary. 343.Sh EXAMPLES 344The following example shows how to change the description 345of 346.Ql sensor0 347in the 348.Ql aiboost0 349device with the 350.Dv ENVSYS_SETDICTIONARY 351.Xr ioctl 2 : 352.Bd -literal 353int 354main(void) 355{ 356 prop_dictionary_t global_dict, sensor_dict; 357 prop_array_t; 358 prop_object_t obj; 359 int fd; 360 361 global_dict = prop_dictionary_create(); 362 sensor_dict = prop_dictionary_create(); 363 array = prop_array_create(); 364 365 if (!prop_dictionary_set(global_dict, "aiboost0", array)) 366 err(EINVAL, "prop_dictionary_set global"); 367 368 obj = prop_string_create_cstring_nocopy("sensor0"); 369 if (obj == NULL || 370 !prop_dictionary_set(dict, "index", obj)) 371 err(EINVAL, "sensor index"); 372 373 prop_object_release(obj); 374 375 /* new description */ 376 obj = prop_string_create_cstring_nocopy("CPU temp"); 377 if (obj == NULL || 378 !prop_dictionary_set(dict, "description", obj)) 379 err(EINVAL, "new description"); 380 381 prop_object_release(obj); 382 383 if (!prop_array_add(array, sensor_dict)) 384 err(EINVAL, "prop_array_add"); 385 386 if ((fd = open(_DEV_SYSMON, O_RDWR)) == \-1) 387 err(EXIT_FAILURE, "open") 388 389 /* we are done, send the dictionary */ 390 error = prop_dictionary_send_ioctl(global_dict, 391 fd, 392 ENVSYS_SETDICTIONARY); 393 prop_object_release(array); 394 prop_object_release(global_dict); 395 (void)close(fd); 396 return error; 397} 398.Ed 399.Sh SEE ALSO 400.Xr envstat 8 , 401.Xr powerd 8 , 402.Xr sysmon_envsys 9 403.Sh HISTORY 404The first 405.Em envsys 406framework first appeared in 407.Nx 1.5 . 408The 409.Em envsys 2 410framework first appeared in 411.Nx 5.0 . 412.Sh AUTHORS 413The (current) 414.Em envsys 2 415framework was implemented by 416.An Juan Romero Pardines . 417Additional input on the design was provided by many 418.Nx 419developers around the world. 420.Pp 421The first 422.Em envsys 423framework was implemented by Jason R. Thorpe, Tim Rightnour, 424and Bill Squier. 425