1.\" $NetBSD: sysmon_envsys.9,v 1.20 2008/11/12 12:35:54 ad Exp $ 2.\" 3.\" Copyright (c) 2007, 2008 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 28, 2008 31.Dt SYSMON_ENVSYS 9 32.Os 33.Sh NAME 34.Nm sysmon_envsys 35.Nd kernel part of the envsys 2 framework 36.Sh SYNOPSIS 37.In dev/sysmon/sysmonvar.h 38.Ft struct sysmon_envsys * 39.Fn sysmon_envsys_create "void" 40.Ft void 41.Fn sysmon_envsys_destroy "struct sysmon_envsys *" 42.Ft int 43.Fn sysmon_envsys_register "struct sysmon_envsys *" 44.Ft void 45.Fn sysmon_envsys_unregister "struct sysmon_envsys *" 46.Ft int 47.Fn sysmon_envsys_sensor_attach "struct sysmon_envsys *, envsys_data_t *" 48.Ft int 49.Fn sysmon_envsys_sensor_detach "struct sysmon_envsys *, envsys_data_t *" 50.Sh DESCRIPTION 51.Pp 52.Nm 53is the kernel part of the 54.Xr envsys 4 55framework. 56With this framework you are able to register and unregister a 57.Nm 58device, attach or detach sensors into a device and enable or disable 59automatic monitoring for some sensors without any user interactivity, 60among other things. 61.Pp 62.Ss HOW TO USE THE FRAMEWORK 63.Pp 64To register a new driver to the 65.Nm 66framework, a 67.Sy sysmon_envsys 68object must be allocated and initialized; the 69.Fn sysmon_envsys_create 70function is used for this. This returns a zero'ed pointer to a sysmon_envsys 71structure and takes care of initialization of some private features. 72.Pp 73Once we have the object we could start initializing sensors (see the 74.Em SENSOR DETAILS 75section for more information) and attaching 76them to the device, this is acomplished by the 77.Fn sysmon_envsys_sensor_attach 78function. This function attachs the envsys_data_t (sensor) specified 79as second argument into the sysmon_envsys object specified in the 80first argument. 81.Pp 82Finally when the sensors are already attached, the device needs to set 83some required (and optional) members of the sysmon_envsys struct before 84calling the 85.Fn sysmon_envsys_register 86function to register the device. 87.Pp 88If there's some error before registering the device, the 89.Fn sysmon_envsys_destroy 90function must be used to detach the sensors previously attached 91and free the sysmon_envsys object allocated by the 92.Fn sysmon_envsys_create 93function. 94.Pp 95The 96.Em sysmon_envsys 97structure is defined as follow 98(only the public members are shown): 99.Bd -literal 100struct sysmon_envsys { 101 const char *sme_name; 102 int sme_flags; 103 int sme_class; 104 uint64_t sme_events_timeout; 105 void *sme_cookie; 106 void (*sme_refresh)(struct sysmon_envsys *, envsys_data_t *); 107}; 108.Ed 109.Pp 110The members have the following meaning: 111.Pp 112.Bl -tag -width "sme_sensor_data_xxxxxxxxx" 113.It Fa sme_class 114This specifies the class of the sysmon envsys device. See the 115.Sy DEVICE CLASSES 116section for more information (OPTIONAL). 117.It Fa sme_name 118The name that will be used in the driver (REQUIRED). 119.It Fa sme_flags 120Additional flags for the 121.Nm 122device. Currently supporting 123.Ar SME_DISABLE_REFRESH . 124If enabled, the 125.Ar sme_refresh 126function callback won't be used 127to refresh sensors data and the driver will use its own method. 128Hence 129.Ar sme_cookie 130won't be necessary either (OPTIONAL). 131.It Fa sme_events_timeout 132This is used to specify the default timeout value that will be used to 133check for critical events if any monitoring flag was set. The value 134is used as seconds (OPTIONAL). 135.El 136.Pp 137.Pp 138If the driver wants to refresh sensors data via the 139.Nm 140framework, the following members must be specified: 141.Pp 142.Bl -tag -width "sme_sensor_data_xxxxxxxxx" 143.It Fa sme_cookie 144Pointer to the device struct (also called 145.Dq softc 146). This may be used in the 147.Sy sme_refresh 148function callback. 149.It Fa sme_refresh 150Pointer to a function that will be used to refresh sensor data in 151the device. This can be used to set the state and other properties of the 152sensor depending of the returned data by the driver. 153.Em NOTE : 154.Em You don't have to refresh all sensors, only the sensor specified by the 155.Sy edata->sensor 156.Em index. 157.El 158.Pp 159Note that it's not necessary to refresh the sensors data before the 160driver is registered, only do it if you need the data in your driver 161to check for a specific condition. 162.Pp 163.Pp 164The timeout value for the monitoring events on a device may be changed via the 165.Em ENVSYS_SETDICTIONARY 166.Xr ioctl 2 167or the 168.Xr envstat 8 169command. 170.Pp 171To unregister a driver previously registered with the 172.Nm 173framework, the 174.Fn sysmon_envsys_unregister 175function must be used. If there were monitoring events registered for the 176driver, they all will be destroyed before the device is unregistered and 177its sensors will be detached; finally the 178.Em sysmon_envsys 179object will be freed, so there's no need to call 180.Fn sysmon_envsys_destroy 181if we are going to unregister a device. 182.Pp 183.Ss DEVICE CLASSES 184The 185.Fa sme_class 186member of the 187.Fa sysmon_envsys 188structure is an optional flag that specifies the class of the 189sysmon envsys device. Currently there are two classes: 190.Pp 191.Bl -tag -width ident 192.It SME_CLASS_ACADAPTER 193.Pp 194This class is for devices that want to act as an 195.Em AC adapter . 196The device writer must ensure that at least there is a 197sensor with 198.Em units 199of 200.Sy ENVSYS_INDICATOR . 201This will be used to report its current state (on/off). 202.It SME_CLASS_BATTERY 203.Pp 204This class is for devices that want to act as an 205.Em Battery . 206The device writer must ensure that at least there are two sensors with 207units of 208.Sy ENVSYS_BATTERY_CAPACITY 209and 210.Sy ENVSYS_BATTERY_CHARGE . 211.Pp 212These two sensors are used to ensure that the battery device won't 213never send a 214.Em low-power 215event to the 216.Xr powerd 8 217daemon (if running) when all battery devices are in a critical state. 218The critical state means that a battery is not currently charging 219and its charge state is low or critical. 220When the 221.Em low-power 222condition is met, an event is sent to the 223.Xr powerd 8 224daemon (if running) and will shutdown the system gracefully via the 225.Fa /etc/powerd/scripts/sensor_battery 226script. 227.Pp 228If 229.Xr powerd 8 230is not running, the system will be powered off via the 231.Xr cpu_reboot 9 232call with the 233.Em RB_POWERDOWN 234flag. 235.Pp 236.El 237.Em NOTE: 238If a 239.Em SME_CLASS_ACADAPTER 240or 241.Em SME_CLASS_BATTERY 242class don't have the sensors required, the 243.Em low-power 244event will never be sent, and the graceful shutdown won't be possible. 245.Ss SENSOR DETAILS 246.Pp 247Each sensor uses a 248.Sy envsys_data_t 249structure, it's defined as follow (only the public members are shown); 250.Bd -literal 251typedef struct envsys_data { 252 uint32_t units; 253 uint32_t state; 254 uint32_t flags; 255 uint32_t rpms; 256 int32_t rfact; 257 int32_t value_cur; 258 int32_t value_max; 259 int32_t value_min; 260 int32_t value_avg; 261 bool monitor; 262 char desc[ENVSYS_DESCLEN]; 263} envsys_data_t; 264.Ed 265.Pp 266The members for the 267.Sy envsys_data_t 268structure have the following meaning: 269.Pp 270.Bl -tag -width cdoscdosrunru 271.It Fa units 272Used to set the units type. 273.It Fa state 274Used to set the current state. 275.It Fa flags 276Used to set additional flags. 277.It Fa rpms 278Used to set the nominal RPM value for 279.Sy fan 280sensors. 281.It Fa rfact 282Used to set the rfact value for 283.Sy voltage 284sensors. 285.It Fa value_cur 286Used to set the current value. 287.It Fa value_max 288Used to set the maximum value. 289.It Fa value_min 290Used to set the minimum value. 291.It Fa value_avg 292Used to set the average value. 293.It Fa monitor 294Used to enable automatic sensor monitoring (by default 295it's disabled). The automatic sensor monitoring will check if 296a condition is met periodically and will send an event to the 297.Xr powerd 8 298daemon (if running). The monitoring event will be registered when this flag 299is 300.Em true 301and one or more of the 302.Em ENVSYS_FMONFOO 303flags were set in the 304.Ar flags 305member. 306.It Fa desc 307Used to set the description string. 308.Em NOTE 309.Em that the description string must be unique in a device, and sensors with 310.Em duplicate or empty description will simply be ignored. 311.El 312.Pp 313Users of this framework must take care about the following points: 314.Bl -bullet 315.It 316The 317.Ar desc 318member needs to have a valid description, unique in a device and non empty 319to be valid. 320.It 321The 322.Ar units 323type must be valid. The following units are defined: 324.Pp 325.Bl -tag -width "ENVSYS_BATTERY_CAPACITY" -compact 326.It ENVSYS_STEMP 327For temperature sensors. 328.It ENVSYS_SFANRPM 329For fan sensors. 330.It ENVSYS_SVOLTS_AC 331For AC Voltage. 332.It ENVSYS_SVOLTS_DC 333For DC Voltage. 334.It ENVSYS_SOHMS 335For Ohms. 336.It ENVSYS_SWATTS 337For Watts. 338.It ENVSYS_SAMPS 339For Ampere. 340.It ENVSYS_SWATTHOUR 341For Watts hour. 342.It ENVSYS_SAMPHOUR 343For Ampere hour. 344.It ENVSYS_INDICATOR 345For sensors that only want a boolean type. 346.It ENVSYS_INTEGER 347For sensors that only want an integer type. 348.It ENVSYS_DRIVE 349For drive sensors. 350.It ENVSYS_BATTERY_CAPACITY 351For Battery device classes. This sensor unit uses the ENVSYS_BATTERY_CAPACITY_* 352values in 353.Ar value_cur 354to report its current capacity to userland. Mandatory if 355.Em sme_class 356is set to 357.Em SME_CLASS_BATTERY . 358.It ENVSYS_BATTERY_CHARGE 359For Battery device classes. This sensor is equivalent to the Indicator type, 360it's a boolean. Use it to specify in what state is the Battery state: 361.Sy true 362if the battery is currently charging or 363.Sy false 364otherwise. Mandatory if 365.Em sme_class 366is set to 367.Em SME_CLASS_BATTERY . 368.El 369.It 370When initializing or refreshing the sensor, the 371.Ar state 372member should be set to a known state (otherwise it will be in 373unknown state). Possible values: 374.Pp 375.Bl -tag -width "ENVSYS_SCRITUNDERXX" -compact 376.It ENVSYS_SVALID 377Sets the sensor to a valid state. 378.It ENVSYS_SINVALID 379Sets the sensor to an invalid state. 380.It ENVSYS_SCRITICAL 381Sets the sensor to a critical state. 382.It ENVSYS_SCRITUNDER 383Sets the sensor to a critical under state. 384.It ENVSYS_SCRITOVER 385Sets the sensor to a critical over state. 386.It ENVSYS_SWARNUNDER 387Sets the sensor to a warning under state. 388.It ENVSYS_SWARNOVER 389Sets the sensor to a warning over state. 390.El 391.Pp 392.It 393The 394.Ar flags 395member accepts one or more of the following flags: 396.Pp 397.Bl -tag -width "ENVSYS_FCHANGERFACTXX" 398.It ENVSYS_FCHANGERFACT 399Marks the sensor with ability to change the 400.Ar rfact 401value on the fly (in voltage sensors). The 402.Ar rfact 403member must be used in the correct place of the code 404that retrieves and converts the value of the sensor. 405.It ENVSYS_FPERCENT 406This uses the 407.Ar value_cur 408and 409.Ar value_max 410members to make a percentage. Both values must be enabled 411and have data. 412.It ENVSYS_FVALID_MAX 413Marks the 414.Ar value_max 415value as valid. 416.It ENVSYS_FVALID_MIN 417Marks the 418.Ar value_min 419value as valid. 420.It ENVSYS_FVALID_AVG 421Marks the 422.Ar value_avg 423value as valid. 424.It ENVSYS_FMONCRITICAL 425Enables and registers a new event to monitor a critical state. 426.It ENVSYS_FMONCRITUNDER 427Enables and registers a new event to monitor a critical under state. 428.It ENVSYS_FMONCRITOVER 429Enables and registers a new event to monitor a critical over state. 430.It ENVSYS_FMONWARNUNDER 431Enables and registers a new event to monitor a warning under state. 432.It ENVSYS_FMONWARNOVER 433Enables and registers a new event to monitor a warning over state. 434.It ENVSYS_FMONSTCHANGED 435Enables and registers a new event to monitor Battery capacity or drive state 436sensors. It won't be effective if the 437.Ar units 438member is not set to 439.Ar ENVSYS_DRIVE 440or 441.Ar ENVSYS_BATTERY_CAPACITY . 442.It ENVSYS_FMONNOTSUPP 443Disallows to set a critical limit via the 444.Em ENVSYS_SETDICTIONARY 445.Xr ioctl(2) . 446This flag has not any effect for monitoring flags set in the driver and it's 447only meant to disable setting critical limits from userland. 448.El 449.Pp 450.Em If the driver has to use any of the 451.Ar value_max , 452.Ar value_min 453.Em or 454.Ar value_avg 455.Em members, they should be marked as valid with the appropiate flag. 456.Pp 457.It 458If 459.Ar units 460is set to 461.Ar ENVSYS_DRIVE , 462there are some predefined states that must be set (only one) 463to the 464.Ar value_cur 465member: 466.Pp 467.Bl -tag -width "ENVSYS_DRIVE_POWERDOWNXX" -compact 468.It ENVSYS_DRIVE_EMPTY 469Drive state is unknown. 470.It ENVSYS_DRIVE_READY 471Drive is ready. 472.It ENVSYS_DRIVE_POWERUP 473Drive is powering up. 474.It ENVSYS_DRIVE_ONLINE 475Drive is online. 476.It ENVSYS_DRIVE_OFFLINE 477Drive is offline. 478.It ENVSYS_DRIVE_IDLE 479Drive is idle. 480.It ENVSYS_DRIVE_ACTIVE 481Drive is active. 482.It ENVSYS_DRIVE_BUILD 483Drive is building. 484.It ENVSYS_DRIVE_REBUILD 485Drive is rebuilding. 486.It ENVSYS_DRIVE_POWERDOWN 487Drive is powering down. 488.It ENVSYS_DRIVE_FAIL 489Drive has failed. 490.It ENVSYS_DRIVE_PFAIL 491Drive has been degraded. 492.It ENVSYS_DRIVE_MIGRATING 493Drive is migrating. 494.It ENVSYS_DRIVE_CHECK 495Drive is checking its state. 496.El 497.Pp 498.It 499If 500.Ar units 501is set to 502.Ar ENVSYS_BATTERY_CAPACITY , 503there are some predefined capacity states that must be set (only one) 504to the 505.Ar value_cur 506member: 507.Pp 508.Bl -tag -width "ENVSYS_BATTERY_CAPACITY_CRITICAL" -compact 509.It ENVSYS_BATTERY_CAPACITY_NORMAL 510Battery charge is in normal capacity. 511.It ENVSYS_BATTERY_CAPACITY_CRITICAL 512Battery charge is in critical capacity. 513.It ENVSYS_BATTERY_CAPACITY_LOW 514Battery charge is in low capacity. 515.It ENVSYS_BATTERY_CAPACITY_WARNING 516Battery charge is in warning capacity. 517.El 518.It 519The 520.Xr envsys 4 521framework expects to have the values converted to 522a unit that can be converted to another one easily. That means the user 523should convert the value returned by the driver to the appropiate unit. 524For example voltage sensors to 525.Sy mV , 526temperature sensors to 527.Sy uK , 528Watts to 529.Sy mW , 530Ampere to 531.Sy mA , 532etc. 533.Pp 534The following types shouldn't need any conversion: 535.Ar ENVSYS_BATTERY_CAPACITY , 536.Ar ENVSYS_BATTERY_CHARGE , 537.Ar ENVSYS_INDICATOR , 538.Ar ENVSYS_INTEGER 539and 540.Ar ENVSYS_DRIVE . 541.Pp 542.Em PLEASE NOTE THAT YOU MUST AVOID USING FLOATING POINT OPERATIONS 543.Em IN KERNEL WHEN CONVERTING THE DATA RETURNED BY THE DRIVER TO THE 544.Em APPROPIATE UNIT, IT'S NOT ALLOWED. 545.Pp 546.El 547.Ss HOW TO ENABLE AUTOMATIC MONITORING IN SENSORS 548The following example illustrates how to enable automatic monitoring 549in a virtual driver for a 550.Em critical 551state in the first sensor 552.Em (sc_sensor[0]): 553.Pp 554.Bd -literal 555int 556mydriver_initialize_sensors(struct mysoftc *sc) 557{ 558 ... 559 /* sensor is initialized with a valid state */ 560 sc->sc_sensor[0].state = ENVSYS_SVALID; 561 562 /* 563 * the monitor member must be true to enable 564 * automatic monitoring. 565 */ 566 sc->sc_sensor[0].monitor = true; 567 568 /* and now we specify the type of the monitoring event */ 569 sc->sc_sensor[0].flags |= ENVSYS_FMONCRITICAL; 570 ... 571} 572 573int 574mydriver_refresh(struct sysmon_envsys *sme, envsys_data_t *edata) 575{ 576 struct mysoftc *sc = sme->sme_cookie; 577 578 /* we get current data from the driver */ 579 edata->value_cur = sc->sc_getdata(); 580 581 /* 582 * if value is too high, mark the sensor in 583 * critical state. 584 */ 585 if (edata->value_cur > MYDRIVER_SENSOR0_HIWAT) { 586 edata->state = ENVSYS_SCRITICAL; 587 /* a critical event will be sent now automatically */ 588 } else { 589 /* 590 * if value is within the limits, and we came from 591 * a critical state make sure to change sensor's state 592 * to valid. 593 */ 594 edata->state = ENVSYS_SVALID; 595 } 596 ... 597} 598.Ed 599.Pp 600.Sh CODE REFERENCES 601This section describes places within the NetBSD source tree where actual 602code implementing the 603.Sy envsys 2 604framework can be found. All pathnames are relative to 605.Pa /usr/src . 606.Pp 607The 608.Sy envsys 2 609framework is implemented within the files: 610.Pp 611.Pa sys/dev/sysmon/sysmon_envsys.c 612.Pp 613.Pa sys/dev/sysmon/sysmon_envsys_events.c 614.Pp 615.Pa sys/dev/sysmon/sysmon_envsys_tables.c 616.Pp 617.Pa sys/dev/sysmon/sysmon_envsys_util.c 618.Sh SEE ALSO 619.Xr envsys 4 , 620.Xr envstat 8 621.Sh HISTORY 622The first 623.Em envsys 624framework first appeared in 625.Nx 1.5 . 626The 627.Em envsys 2 628framework first appeared in 629.Nx 5.0 . 630.Sh AUTHORS 631The (current) 632.Em envsys 2 633framework was implemented by 634.An Juan Romero Pardines . 635Additional input on the design was provided by many 636.Nx 637developers around the world. 638.Pp 639The first 640.Em envsys 641framework was implemented by Jason R. Thorpe, Tim Rightnour 642and Bill Squier. 643