describe new functions to handle sensors; by Constantine A. Murenin

2 files changed, 76 insertions, 47 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 54a83ab7d74..8c78d8cfb5f 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.117 2006/11/27 17:00:09 dlg Exp $
+#	$OpenBSD: Makefile,v 1.118 2006/12/23 17:53:09 deraadt Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -20,7 +20,7 @@ MAN=	altq.9 audio.9 autoconf.9 bio_register.9 boot.9 buffercache.9 \
 	panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
 	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 rwlock.9 \
-	sensor_add.9 \
+	sensor_attach.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
 	style.9 syscall.9 systrace.9 sysctl_int.9 \
 	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_busy.9 \
@@ -244,9 +244,13 @@ MLINKS+=psignal.9 pgsignal.9 psignal.9 gsignal.9
 MLINKS+=rasops.9 rasops_init.9 rasops.9 rasops_reconfig.9
 MLINKS+=shutdownhook_establish.9 shutdownhook_disestablish.9
 MLINKS+=mountroothook_establish.9 mountroothook_disestablish.9
-MLINKS+=sensor_add.9 sensor_del.9 sensor_add.9 sensor_get.9 \
-	sensor_add.9 sensor_task_register.9 \
-	sensor_add.9 sensor_task_unregister.9
+MLINKS+=sensor_attach.9 sensordev_install.9 \
+	sensor_attach.9 sensordev_deinstall.9 \
+	sensor_attach.9 sensordev_get.9 \
+	sensor_attach.9 sensor_detach.9 \
+	sensor_attach.9 sensor_find.9 \
+	sensor_attach.9 sensor_task_register.9 \
+	sensor_attach.9 sensor_task_unregister.9
 MLINKS+=sleep.9 tsleep.9 sleep.9 wakeup.9
 MLINKS+=spl.9 spl0.9 spl.9 splassert.9 spl.9 splbio.9 spl.9 splclock.9 \
 	spl.9 splhigh.9 spl.9 spllowersoftclock.9 \
diff --git a/share/man/man9/sensor_add.9 b/share/man/man9/sensor_attach.9
index 06809c33c0b..d25669b1ec7 100644
--- a/share/man/man9/sensor_add.9
+++ b/share/man/man9/sensor_attach.9
@@ -1,6 +1,7 @@
-.\"	$OpenBSD: sensor_add.9,v 1.3 2006/10/10 14:07:56 dlg Exp $
+.\"	$OpenBSD: sensor_attach.9,v 1.1 2006/12/23 17:53:09 deraadt Exp $
 .\"
 .\" Copyright (c) 2006 Michael Knudsen <mk@openbsd.org>
+.\" Copyright (c) 2006 Constantine A. Murenin <cnst+openbsd@bugmail.mojo.ru>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -27,69 +28,90 @@
 .Dt SENSOR_ADD 9
 .Os
 .Sh NAME
-.Nm sensor_add ,
-.Nm sensor_del ,
-.Nm sensor_get ,
+.Nm sensor_attach ,
+.Nm sensor_detach ,
+.Nm sensor_find ,
+.Nm sensordev_install ,
+.Nm sensordev_deinstall ,
+.Nm sensordev_get ,
 .Nm sensor_task_register ,
 .Nm sensor_task_unregister
-.Nd sensor framework
+.Nd sensors framework
 .Sh SYNOPSIS
 .Fd #include <sys/sensors.h>
 .Ft void
-.Fn "sensor_add" "struct sensor *sens"
+.Fn "sensordev_install" "struct sensordev *sensdev"
 .Ft void
-.Fn "sensor_del" "struct sensor *sens"
+.Fn "sensordev_deinstall" "struct sensordev *sensdev"
+.Ft struct sensordev
+.Fn "*sensordev_get" "int devnum"
+.Pp
+.Ft void
+.Fn "sensor_attach" "struct sensordev *sensdev" "struct sensor *sens"
+.Ft void
+.Fn "sensor_detach" "struct sensordev *sensdev" "struct sensor *sens"
 .Ft struct sensor
-.Fn "*sensor_get" "int num"
+.Fn "*sensor_find" "int devnum" "enum sensor_type stype" "int numt"
+.Pp
 .Ft int
 .Fn "sensor_task_register" "void *arg" "void (*func)(void *)" "int period"
 .Ft void
 .Fn "sensor_task_unregister" "void *arg"
 .Sh DESCRIPTION
 The
-.Nm sensor
-framework API provides a mechanism to manipulate the sensor framework
-available under the
+sensors
+framework API provides a mechanism for manipulation of hardware sensors
+that are available under the
 .Va hw.sensors
-.Xr sysctl 8 .
+.Xr sysctl 8
+tree.
 .Pp
-.Fn sensor_add
-adds a sensor specified by the
+.Fn sensor_attach
+adds sensor specified by the
 .Pa sens
+argument to sensor device specified by the
+.Pa sensdev
 argument.
-.Fn sensor_del
-removes a sensor previously added by
-.Fn sensor_add .
-Both
-.Fn sensor_add
-and
-.Fn sensor_del
-take an argument of a pointer to a
-.Vt struct sensor ,
-defined in
-.Aq Pa sys/sensors.h ,
-as:
-.Bd -literal
-struct sensor {
-	SLIST_ENTRY(sensor) list;
-	int num;			/* sensor number */
-	char device[16];		/* device name */
-	enum sensor_type type;		/* sensor type */
-	char desc[32];			/* sensor description */
-	int64_t value;			/* current value */
-	u_int rfact;			/* resistor factor */
-	enum sensor_status status;	/* sensor status */
-	int flags;			/* sensor flags */
-	struct timeval tv;		/* sensor value last change time */
-};
-.Ed
+.Fn sensor_detach
+can be used to remove sensors previously added by
+.Fn sensor_attach .
 .Pp
-.Fn sensor_get
-takes an index parameter and returns a pointer to the corresponding
+.Fn sensordev_install
+registers sensor device specified by the
+.Pa sensdev
+argument so that all sensors that are attached to the device become
+accessible via the sysctl interface.
+.Fn sensordev_deinstall
+can be used to remove sensor devices previously registered by
+.Fn sensordev_install .
+.Pp
+.Fn sensordev_get
+takes ordinal number
+.Pa devnum
+specifying sensor device and
+returns a pointer to the corresponding
+.Vt struct sensordev ,
+or
+.Dv NULL
+if no such sensor device exists.
+.Pp
+.Fn sensor_find
+takes ordinal number
+.Pa devnum
+specifying sensor device, sensor type
+.Pa stype
+and ordinal number of sensor of such type
+.Pa numt ,
+and returns a pointer to the corresponding
 .Vt struct sensor ,
 or
 .Dv NULL
 if no such sensor exists.
+.Fn sensor_find
+will always return
+.Dv NULL
+if the corresponding sensor devices are not registered by
+.Fn sensordev_install .
 .Pp
 Drivers are responsible for retrieving, interpreting, and normalising
 sensor values and updating the sensor struct periodically.
@@ -134,3 +156,6 @@ and first appeared in
 .An David Gwynne Aq dlg@openbsd.org
 later extended it for
 .Ox 3.8 .
+.An Constantine A. Murenin Aq cnst+openbsd@bugmail.mojo.ru
+extended it even further by introducing the concept of sensor devices in
+.Ox 4.1 .