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