1.\" $OpenBSD: sensor_attach.9,v 1.4 2007/03/22 16:55:31 deraadt Exp $ 2.\" 3.\" Copyright (c) 2006 Michael Knudsen <mk@openbsd.org> 4.\" Copyright (c) 2006 Constantine A. Murenin <cnst+openbsd@bugmail.mojo.ru> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 17.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 18.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 19.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 20.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd August 19, 2007 28.Dt SENSOR_ATTACH 9 29.Os 30.Sh NAME 31.Nm sensor_attach , 32.Nm sensor_detach , 33.Nm sensordev_install , 34.Nm sensordev_deinstall , 35.Nm sensor_task_register , 36.Nm sensor_task_unregister 37.Nd sensors framework 38.Sh SYNOPSIS 39.In sys/time.h 40.In sys/sensors.h 41.Ft void 42.Fn "sensordev_install" "struct ksensordev *sensdev" 43.Ft void 44.Fn "sensordev_deinstall" "struct ksensordev *sensdev" 45.Ft void 46.Fn "sensor_attach" "struct ksensordev *sensdev" "struct ksensor *sens" 47.Ft void 48.Fn "sensor_detach" "struct ksensordev *sensdev" "struct ksensor *sens" 49.Ft int 50.Fn "sensor_task_register" "void *arg" "void (*func)(void *)" "int period" 51.Ft void 52.Fn "sensor_task_unregister" "void *arg" 53.Sh DESCRIPTION 54The 55sensors 56framework API provides a mechanism for manipulation of hardware sensors 57that are available under the 58.Va hw.sensors 59.Xr sysctl 8 60tree. 61.Pp 62The 63.Fn sensor_attach 64function adds the sensor specified by the 65.Fa sens 66argument to the sensor device specified by the 67.Fa sensdev 68argument. 69The 70.Fn sensor_detach 71function can be used to remove sensors previously added by 72.Fn sensor_attach . 73.Pp 74The 75.Fn sensordev_install 76function registers the sensor device specified by the 77.Fa sensdev 78argument so that all sensors that are attached to the device become 79accessible via the sysctl interface. 80The 81.Fn sensordev_deinstall 82function can be used to remove sensor devices previously registered by 83.Fn sensordev_install . 84.Pp 85Drivers are responsible for retrieving, interpreting and normalising 86sensor values and updating the sensor struct periodically. 87If the driver needs process context, for example to sleep, it can 88register a task with the sensor framework. 89.Pp 90The 91.Fn sensor_task_register 92function is used to register a periodic task to update sensors. 93The 94.Fa func 95argument is a pointer to the function to run with an interval of 96.Fa period 97seconds. 98The 99.Fa arg 100parameter is the argument given to the 101.Fa func 102function. 103The 104.Fn sensor_task_unregister 105function removes all tasks previously registered with 106.Fn sensor_task_register 107with an argument of 108.Fa arg . 109.Sh COMPATIBILITY 110.Ss sensor_task 111The 112.Fn sensor_task_register 113and 114.Fn sensor_task_unregister 115functions that are included in 116.Ox 4.2 117and later 118are not compatible with 119.Dx . 120.Dx 121includes an implementation that is similar and compatible 122with an earlier version of 123these 124.Fn sensor_task 125functions that was available from 126.Ox 3.9 127until 128.Ox 4.1 . 129.Pp 130Drivers that only call 131.Fn sensor_task_register 132and do not check its return value are not affected by this 133.Fn sensor_task 134compatibility notice. 135.Sh SEE ALSO 136.Xr systat 1 , 137.Xr sysctl 3 , 138.Xr sensorsd 8 , 139.Xr sysctl 8 140.Sh HISTORY 141The sensor framework was written by 142.An Alexander Yurchenko Aq Mt grange@openbsd.org 143and first appeared in 144.Ox 3.4 . 145.An David Gwynne Aq Mt dlg@openbsd.org 146later extended it for 147.Ox 3.8 . 148.An Constantine A. Murenin Aq Mt cnst+openbsd@bugmail.mojo.ru 149extended it even further by introducing the concept of sensor devices in 150.Ox 4.1 . 151.Pp 152The framework was ported to 153.Fx 154by 155.An Constantine A. Murenin 156as a Google Summer of Code 2007 project. 157