[src/uebayasi-xip]: src/share/man/man9 Use a typedef to define the prototype ...

[pgoyette <pgoyette%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/d2dca2ba74ad
branches:  uebayasi-xip
changeset: 751649:d2dca2ba74ad
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Sun Apr 11 01:12:29 2010 +0000

description:
Use a typedef to define the prototype of the per-sensor callback.

Update manpage for the prototype, and fix a fubar'd Cross-reference.

diffstat:

 share/man/man9/sysmon_envsys.9 |  727 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 727 insertions(+), 0 deletions(-)

diffs (truncated from 731 to 300 lines):

diff -r 27510a165f2d -r d2dca2ba74ad share/man/man9/sysmon_envsys.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/sysmon_envsys.9    Sun Apr 11 01:12:29 2010 +0000
@@ -0,0 +1,727 @@
+.\"    $NetBSD: sysmon_envsys.9,v 1.40.2.2 2010/04/11 01:12:29 pgoyette Exp $
+.\"
+.\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Juan Romero Pardines.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd April 10, 2010
+.Dt SYSMON_ENVSYS 9
+.Os
+.Sh NAME
+.Nm sysmon_envsys
+.Nd kernel part of the envsys 2 framework
+.Sh SYNOPSIS
+.In dev/sysmon/sysmonvar.h
+.Ft struct sysmon_envsys *
+.Fn sysmon_envsys_create "void"
+.Ft void
+.Fn sysmon_envsys_destroy "struct sysmon_envsys *"
+.Ft int
+.Fn sysmon_envsys_register "struct sysmon_envsys *"
+.Ft void
+.Fn sysmon_envsys_unregister "struct sysmon_envsys *"
+.Ft int
+.Fn sysmon_envsys_sensor_attach "struct sysmon_envsys *" "envsys_data_t *"
+.Ft int
+.Fn sysmon_envsys_sensor_detach "struct sysmon_envsys *" "envsys_data_t *"
+.Ft void
+.Fn sysmon_envsys_sensor_event "struct sysmon_envsys *" "envsys_data_t *" "int"
+.Ft void
+.Fn sysmon_envsys_foreach_sensor "sysmon_envsys_callback_t" "void *" "bool"
+.Ft int
+.Fn sysmon_envsys_update_limits "struct sysmon_envsys *" "envsys_data_t *"
+.Sh DESCRIPTION
+.Pp
+.Nm
+is the kernel part of the
+.Xr envsys 4
+framework.
+With this framework you are able to register and unregister a
+.Nm
+device, attach or detach sensors into a device, and enable or disable
+automatic monitoring for some sensors without any user interactivity,
+among other things.
+.Ss HOW TO USE THE FRAMEWORK
+To register a new driver to the
+.Nm
+framework, a
+.Em sysmon_envsys
+object must be allocated and initialized; the
+.Fn sysmon_envsys_create
+function is used for this.
+This returns a zero'ed pointer to a
+.Em sysmon_envsys
+structure.
+.Pp
+Once the object has been initialized,
+actual sensors may be initialized and attached (see the
+.Sx SENSOR DETAILS
+section for more information).
+This is accomplished by the
+.Fn sysmon_envsys_sensor_attach
+function, which will attach the
+.Em envsys_data_t
+(a sensor) specified as second argument into the
+.Em sysmon_envsys
+object specified in the first argument.
+.Pp
+Finally, after all sensors have been attached,
+the device needs to set some required (and optional) members of the
+.Em sysmon_envsys
+structure before calling the
+.Fn sysmon_envsys_register
+function to register the device.
+.Pp
+In case of errors during the initialization, the
+.Fn sysmon_envsys_destroy
+function should be used.
+This detachs all previously attached sensors and deallocates the
+.Em sysmon_envsys
+object.
+.Pp
+Some sensors can be monitored, and when the sensor value changes an event
+can be delivered to the
+.Xr powerd 8
+daemon.
+Sensor monitoring can be performed by the
+.Nm
+framework on a polled basis.
+Alternatively, the sensor's device driver can call the
+.Fn sysmon_envsys_sensor_event
+function to deliver the event without waiting for the device to be polled.
+.Pp
+The
+.Fn sysmon_envsys_foreach_sensor
+function can be used by other parts of the kernel to iterate over all
+registered sensors.
+This capability is used by the
+.Xr i386/apm 4
+driver to summarize the state of all battery sensors.
+.Pp
+Drivers can also call the
+.Fn sysmon_envsys_update_limits
+function when it is necessary to reinitialize a sensor's threshhold values.
+This is used by the
+.Xr acpibat 4
+driver when a new battery is inserted.
+.Pp
+The
+.Em sysmon_envsys
+structure is defined as follows
+(only the public members are shown):
+.Bd -literal
+struct sysmon_envsys {
+       const char      *sme_name;
+       int             sme_flags;
+       int             sme_class;
+       uint64_t        sme_events_timeout;
+       void            *sme_cookie;
+       void (*sme_refresh)(struct sysmon_envsys *, envsys_data_t *);
+       void (*sme_set_limits)(struct sysmon_envsys *, envsys_data_t *,
+                              sysmon_envsys_lim_t *, uint32_t *);
+       void (*sme_get_limits)(struct sysmon_envsys *, envsys_data_t *,
+                              sysmon_envsys_lim_t *, uint32_t *);
+};
+.Ed
+.Pp
+The members have the following meaning:
+.Pp
+.Bl -tag -width "sme_events_timeout"
+.It Fa sme_class
+This specifies the class of the sysmon envsys device.
+See the
+.Sy DEVICE CLASSES
+section for more information (OPTIONAL).
+.It Fa sme_name
+The name that will be used in the driver (REQUIRED).
+.It Fa sme_flags
+Additional flags for the
+.Nm
+device.
+Currently supporting
+.Ar SME_DISABLE_REFRESH .
+If enabled, the
+.Ar sme_refresh
+function callback won't be used
+to refresh sensor data and the driver will use its own method (OPTIONAL).
+.It Fa sme_events_timeout
+This is used to specify the default timeout value (in seconds) that will be
+used to check for critical events if any monitoring flag was set (OPTIONAL).
+.El
+.Pp
+If the driver wants to refresh sensors data via the
+.Nm
+framework, the following members may be specified:
+.Pp
+.Bl -tag -width "sme_events_timeout"
+.It Fa sme_cookie
+Typically a pointer to the device struct (also called
+.Dq softc ) .
+This may be used in the
+.Sy sme_refresh ,
+.Sy sme_get_limits ,
+or
+.Sy sme_set_limits
+function callbacks.
+.It Fa sme_refresh
+Pointer to a function that will be used to refresh sensor data in
+the device.
+This can be used to set the state and other properties of the
+sensor depending on the data returned by the driver.
+.Em NOTE :
+.Em You don't have to refresh all sensors, only the sensor specified by the
+.Sy edata-\*[Gt]sensor
+.Em index .
+If this member is not specified, the device driver will be totally
+responsible for all updates of this sensor; the
+.Nm
+framework will not be able to update the sensor value.
+.It Fa sme_get_limits
+Pointer to a function that will be used to obtain from the driver the
+initial limits (or thresholds) used when monitoring a sensor's value.
+(See the
+.Sx SENSOR DETAILS
+section for more information.)
+If this member is not specified, the
+.Dv ENVSYS_FMONLIMITS
+flag will be ignored, and limit monitoring will not occur until
+appropriate limits are enabled from userland via
+.Xr envstat 8 .
+.It Fa sme_set_limits
+Pointer to a function that alerts the device driver whenever monitoring
+limits (or thresholds) are updated by the user.
+Setting this function allows the device driver to reprogram hardware
+limits (if provided by the device) when the user-specificied limits are
+updated, and gives the driver direct control over setting the sensor's
+state based on hardware status.
+.Pp
+The
+.Fa sme_set_limits
+callback can be invoked with the third argument (a pointer to the new
+limits) set to a
+.Dv NULL
+pointer.
+Device drivers must recognize this as a request to restore the sensor
+limits to their original, boot-time values.
+.Pp
+If the
+.Fa sme_set_limits
+member is not specified, the device driver is not informed of changes to
+the sensor's limit values, and the
+.Nm
+framework performs all limit checks in software.
+.El
+.Pp
+Note that it's not necessary to refresh the sensors data before the
+driver is registered, only do it if you need the data in your driver
+to check for a specific condition.
+.Pp
+The timeout value for the monitoring events on a device may be changed via the
+.Dv ENVSYS_SETDICTIONARY
+.Xr ioctl 2
+or the
+.Xr envstat 8
+command.
+.Pp
+To unregister a driver previously registered with the
+.Nm
+framework, the
+.Fn sysmon_envsys_unregister
+function must be used.
+If there were monitoring events registered for the
+driver, they all will be destroyed before the device is unregistered and
+its sensors are detached.
+Finally the
+.Em sysmon_envsys
+object will be freed, so there's no need to call
+.Fn sysmon_envsys_destroy .
+.Ss DEVICE CLASSES
+The
+.Fa sme_class
+member of the
+.Fa sysmon_envsys
+structure is an optional flag that specifies the class of the
+sysmon envsys device.
+Currently there are two classes:
+.Pp
+.Bl -tag -width ident
+.It SME_CLASS_ACADAPTER
+.Pp
+This class is for devices that want to act as an
+.Em AC adapter .
+The device writer must ensure that at least there is a
+sensor with
+.Em units
+of
+.Dv ENVSYS_INDICATOR .
+This will be used to report its current state (on/off).
+.It SME_CLASS_BATTERY
+.Pp
+This class is for devices that want to act as a
+.Em Battery .
+The device writer must ensure that at least there are two sensors with
+units of
+.Dv ENVSYS_BATTERY_CAPACITY
+and
+.Dv ENVSYS_BATTERY_CHARGE .
+.Pp
+These two sensors are used to ensure that the battery device can
+send a
+.Em low-power
+event to the
+.Xr powerd 8
+daemon (if running) when all battery devices are in a critical state.