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