[src/trunk]: src/share/man/man9 Document also the sysmon power switches; sysm...

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

details:   https://anonhg.NetBSD.org/src/rev/3b542c7bef12
branches:  trunk
changeset: 751155:3b542c7bef12
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Jan 26 14:00:38 2010 +0000

description:
Document also the sysmon power switches; sysmon_pswitch(9).

diffstat:

 share/man/man9/Makefile         |    9 +-
 share/man/man9/sysmon_pswitch.9 |  136 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 142 insertions(+), 3 deletions(-)

diffs (170 lines):

diff -r 09feec9e9b7d -r 3b542c7bef12 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Tue Jan 26 12:59:50 2010 +0000
+++ b/share/man/man9/Makefile   Tue Jan 26 14:00:38 2010 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.312 2010/01/26 08:14:09 jruoho Exp $
+#       $NetBSD: Makefile,v 1.313 2010/01/26 14:00:38 jruoho Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -48,8 +48,8 @@
        secmodel_suser.9 setjmp.9 shutdownhook_establish.9 \
        signal.9 sockopt.9 softintr.9 spl.9 splraiseipl.9 \
        store.9 suspendsched.9 \
-       sysctl.9 sysmon_envsys.9 sysmon_taskq.9 tc.9 tcp_congctl.9 \
-       timecounter.9 time_second.9 todr.9 tvtohz.9 \
+       sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
+       tcp_congctl.9 timecounter.9 time_second.9 todr.9 tvtohz.9 \
        uiomove.9 ucom.9 userret.9 \
        vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
        video.9 vme.9 \
@@ -659,6 +659,9 @@
        sysmon_envsys.9 sysmon_envsys_unregister.9 \
        sysmon_envsys.9 sysmon_envsys_sensor_attach.9 \
        sysmon_envsys.9 sysmon_envsys_sensor_detach.9
+MLINKS+=sysmon_pswitch.9 sysmon_pswitch_event.9 \
+       sysmon_pswitch.9 sysmon_pswitch_register.9 \
+       sysmon_pswitch.9 sysmon_pswitch_unregister.9
 MLINKS+=sysmon_taskq.9 sysmon_task_queue_fini.9 \
        sysmon_taskq.9 sysmon_task_queue_init.9 \
        sysmon_taskq.9 sysmon_task_queue_preinit.9 \
diff -r 09feec9e9b7d -r 3b542c7bef12 share/man/man9/sysmon_pswitch.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/sysmon_pswitch.9   Tue Jan 26 14:00:38 2010 +0000
@@ -0,0 +1,136 @@
+.\" $NetBSD: sysmon_pswitch.9,v 1.1 2010/01/26 14:00:38 jruoho Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jukka Ruohonen.
+.\"
+.\" 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 January 26, 2010
+.Dt SYSMON_PSWITCH 9
+.Os
+.Sh NAME
+.Nm sysmon_pswitch
+.Nd framework for power switches
+.Sh SYNOPSIS
+.In dev/sysmon/sysmonvar.h
+.Ft int
+.Fn sysmon_pswitch_register "struct sysmon_pswitch *smpsw"
+.Ft void
+.Fn sysmon_pswitch_unregister "struct sysmon_pswitch *smpsw"
+.Ft void
+.Fn sysmon_pswitch_event "struct sysmon_pswitch *smpsw" "int event"
+.Sh DESCRIPTION
+The machine-independent
+.Nm
+provides a framework for power management.
+The interface has been largely superceded by the
+.Xr pmf 9
+framework, but
+.Nm
+is still used to manage power switches as well as
+related mechanical adapters and buttons.
+These are encapsulated in the following structure:
+.Bd -literal
+struct sysmon_pswitch {
+       const char *smpsw_name;         /* power switch name */
+       int smpsw_type;                 /* power switch type */
+
+       LIST_ENTRY(sysmon_pswitch) smpsw_list;
+};
+.Ed
+.Pp
+Unsurprisingly,
+.Fa smpsw_name
+specifies the name of the power switch and
+.Fa smpsw_type
+defines the type of it.
+The following types are defined:
+.Bl -tag -width PSWITCH_HK_VENDOR_BUTTON -compat -offset indent
+.It PSWITCH_TYPE_POWER
+.It PSWITCH_TYPE_SLEEP
+.It PSWITCH_TYPE_LID
+.It PSWITCH_TYPE_RESET
+.It PSWITCH_TYPE_ACADAPTER
+.It PSWITCH_TYPE_HOTKEY
+.El
+.Pp
+If the type is
+.Dv PSWITCH_TYPE_HOTKEY ,
+there are few predefined names that can be used for
+.Fa smpsw_name :
+.Bl -tag -width PSWITCH_HK_VENDOR_BUTTON -compat -offset indent
+.It PSWITCH_HK_DISPLAY_CYCLE
+.Em display-cycle
+.It PSWITCH_HK_LOCK_SCREEN
+.Em lock-screen
+.It PSWITCH_HK_BATTERY_INFO
+.Em battery-info
+.It PSWITCH_HK_EJECT_BUTTON
+.Em eject-button
+.It PSWITCH_HK_ZOOM_BUTTON
+.Em zoom-button
+.It PSWITCH_HK_VENDOR_BUTTON
+.Em vendor-button
+.El
+.Pp
+Once a power switch event has been proceeded,
+.Nm
+will inform the user space
+.Xr powerd 8 ,
+which will possibly execute a script matching the type of the power switch.
+.Sh FUNCTIONS
+After the
+.Em sysmon_pswitch
+structure has been initialized,
+a new power switch device can be registered by using
+.Fn sysmon_pswitch_register .
+The device can be detached from the framework by
+.Fn sysmon_pswitch_unregister .
+.Pp
+The
+.Fn sysmon_pswitch_event
+is used to signal a new power switch event.
+There are two possibilities for the value of
+.Fa event :
+.Bl -tag -width PSWITCH_HK_VENDOR_BUTTON -offset indent
+.It PSWITCH_EVENT_PRESSED
+A button has been pressed, the lid has been closed, the AC adapter is off, etc.
+.It PSWITCH_EVENT_RELEASED
+A button has been released, the lid is open, the AC adapter is on, etc.
+.El
+.Pp
+The corresponding events in
+.Xr powerd 8
+are
+.Em pressed
+and
+.Em released .
+.Sh SEE ALSO
+.Xr powerd 8 ,
+.Xr pmf 9 ,
+.Xr sysmon_envsys 9 ,
+.Xr sysmon_taskq 9
+.Sh AUTHORS
+.An Jason R. Thorpe Aq thorpej%NetBSD.org@localhost