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