share/man/man4/envsys.4

   1 .\"     $NetBSD: envsys.4,v 1.44 2009/10/14 23:18:39 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 June 12, 2009
  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
  39 The
  40 .Nm
  41 framework provides support to handle hardware monitor devices.
  42 Hardware monitoring chips are able to report values from different types of
  43 sensors.
  44 .Pp
  45 The
  46 .Nm
  47 framework consists of two parts:
  48 .Pp
  49 .Bl -enum -offset indent -compact
  50 .It
  51 the userland part, to receive the current sensor data and
  52 to set some properties on sensors:
  53 .Xr envstat 8 .
  54 .It
  55 The kernel part that is able to talk to the drivers providing sensor
  56 data:
  57 .Xr sysmon_envsys 9 .
  58 .El
  59 .Pp
  60 The
  61 .Nm
  62 framework uses
  63 .Xr proplib 3
  64 for communication between kernel and user space.
  65 The following
  66 .Xr ioctl 2
  67 types are available:
  68 .Pp
  69 .Bl -tag -width XX
  70 .It Dv ENVSYS_GETDICTIONARY Pq prop_dictionary_t
  71 .Pp
  72 This
  73 .Xr ioctl 2
  74 is used to receive the global dictionary that is being used in
  75 the kernel by the
  76 .Xr sysmon_envsys 9
  77 framework.
  78 It will contain an array of dictionaries per device
  79 and one dictionary per sensor plus another special dictionary that
  80 contains the properties for a device.
  81 Each sensor dictionary will have their own characteristics and values.
  82 .Pp
  83 The following XML property list represents a virtual device
  84 .Dq device0
  85 with one sensor
  86 .Dq sensor0
  87 and all available properties set on it, plus another sensor for
  88 the
  89 .Dq device-properties
  90 dictionary (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
 155 Let's explain some more about those objects:
 156 .Bl -tag -width "monitoring-state-critical-overxx"
 157 .It Fa allow-rfact
 158 Set to
 159 .Em true
 160 means that the sensor is able to change the resistor factor,
 161 only used in Voltage sensors.
 162 .It Fa avg-value
 163 Current average value in the sensor.
 164 .It Fa battery-capacity
 165 Current capacity state for a battery capacity sensor.
 166 .It Fa critical-capacity
 167 Critical capacity set previously by the
 168 .Dv ENVSYS_SETDICTIONARY
 169 .Xr ioctl 2 .
 170 Only available on sensors with the
 171 .Em want-percentage
 172 object enabled.
 173 .It Fa critical-max
 174 Critical max limit set previously by the
 175 .Dv ENVSYS_SETDICTIONARY
 176 .Xr ioctl 2 .
 177 .It Fa critical-min
 178 Critical min limit set previously by the
 179 .Dv ENVSYS_SETDICTIONARY
 180 .Xr ioctl 2 .
 181 .It Fa cur-value
 182 Current value in the sensor.
 183 .It Fa description
 184 Description of the sensor.
 185 .It Fa index
 186 Index position of the sensor.
 187 .It Fa max-value
 188 Current max value in the sensor.
 189 .It Fa min-value
 190 Current min value in the sensor.
 191 .It Fa monitoring-state-critical
 192 If true, the driver has enabled the flag to monitor a critical state.
 193 .It Fa monitoring-state-hw-range-limits
 194 If true, the driver has enabled the flag to monitor warning or critical
 195 limits.
 196 .It Fa monitoring-state-state-changed
 197 If true, the driver has enabled the flag to monitor for state changes in
 198 a drive or Battery state sensor.
 199 .It Fa monitoring-supported
 200 If true, critical/warning capacity/max/min limits may be set by the
 201 .Dv ENVSYS_SETDICTIONARY
 202 .Xr ioctl 2 .
 203 .It Fa state
 204 Current state in the sensor.
 205 .It Fa type
 206 Type of unit in the sensor.
 207 .It Fa want-percentage
 208 If true,
 209 .Em max-value
 210 and
 211 .Em cur-value
 212 are valid and a percentage may be computed from them.
 213 .It Fa warning-capacity
 214 Warning capacity set previously by the
 215 .Dv ENVSYS_SETDICTIONARY
 216 .Xr ioctl 2 .
 217 Only available on sensors with the
 218 .Em want-percentage
 219 object enabled.
 220 .It Fa warning-max
 221 Warning max limit set previously by the
 222 .Dv ENVSYS_SETDICTIONARY
 223 .Xr ioctl 2 .
 224 .It Fa warning-min
 225 Warning 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
 231 This
 232 .Xr ioctl 2
 233 is used to remove all properties that are currently set via the
 234 .Dv ENVSYS_SETDICTIONARY
 235 ioctl.
 236 The values will be set to defaults, the ones that the driver uses.
 237 .Pp
 238 Only 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
 244 It is a boolean object and must be set to
 245 .Em true
 246 to be effective.
 247 .It Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t
 248 This
 249 .Xr ioctl 2
 250 is used to send a dictionary with new properties that should be
 251 processed by the
 252 .Nm
 253 framework.
 254 Only a set of predefined keywords are recognized by the kernel part.
 255 The following is the property list representation
 256 of a dictionary with all recognized and required keywords that
 257 a 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
 279 Also if some properties in a device need to be changed, the
 280 .Dq device-properties
 281 dictionary must be used.
 282 At this moment only the
 283 .Dq refresh-timeout
 284 property is understood.
 285 This 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
 296 A dictionary sent to the kernel with this
 297 .Xr ioctl 2
 298 should 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
 322 The named device will be an array and will contain dictionaries,
 323 any dictionary needs to have the
 324 .Em index
 325 object specifying the sensor that is required for the new properties.
 326 .Pp
 327 If an unknown object was sent with the dictionary,
 328 .Er EINVAL
 329 will be returned, or if the sensor does not support changing
 330 rfact (voltage sensors) or critical/warning/capacity limits,
 331 .Er ENOTSUP
 332 will be returned.
 333 .El
 334 .Sh NOTES
 335 When setting a critical/warning max or min limit with the
 336 .Dv ENVSYS_SETDICTIONARY
 337 .Xr ioctl 2 ,
 338 the user must be aware that
 339 .Xr sysmon_envsys 9
 340 expects to have a proper unit, so the value must be converted.
 341 Please see
 342 .Xr sysmon_envsys 9
 343 for more information.
 344 .Pp
 345 Also when setting a critical or warning capacity limit, the formula to send a
 346 proper value to
 347 .Xr sysmon_envsys 9
 348 is the following:
 349 .Em value = (value / 100) * max value .
 350 The max value is available in the sensor's dictionary.
 351 .Sh EXAMPLES
 352 The following example shows how to change the description
 353 of
 354 .Ql sensor0
 355 in the
 356 .Ql aiboost0
 357 device with the
 358 .Dv ENVSYS_SETDICTIONARY
 359 .Xr ioctl 2 :
 360 .Bd -literal
 361 int
 362 main(void)
 363 {
 364         prop_dictionary_t global_dict, sensor_dict;
 365         prop_array_t array;
 366         prop_object_t obj;
 367         int fd;
 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, "aiboost0", 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(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 temp");
 385         if (obj == NULL ||
 386             !prop_dictionary_set(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
 412 The first
 413 .Em envsys
 414 framework first appeared in
 415 .Nx 1.5 .
 416 The
 417 .Em envsys 2
 418 framework first appeared in
 419 .Nx 5.0 .
 420 .Sh AUTHORS
 421 The (current)
 422 .Em envsys 2
 423 framework was implemented by
 424 .An Juan Romero Pardines .
 425 Additional input on the design was provided by many
 426 .Nx
 427 developers around the world.
 428 .Pp
 429 The first
 430 .Em envsys
 431 framework was implemented by Jason R. Thorpe, Tim Rightnour,
 432 and Bill Squier.