Add man pages for the kernel power hook mechanisms.

3 files changed, 164 insertions, 4 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index fc5cef601cd..f78024ec95a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,13 +1,13 @@
-#	$OpenBSD: Makefile,v 1.22 2000/04/28 05:54:07 angelos Exp $
+#	$OpenBSD: Makefile,v 1.23 2000/07/01 14:45:44 aaron Exp $
 #       $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
 
 MAN=	audio.9 boot.9 copy.9 crypto.9 ctxsw.9 disk.9 disklabel.9 \
-	doshutdownhooks.9 fetch.9 fork1.9 \
+	dopowerhooks.9 doshutdownhooks.9 fetch.9 fork1.9 \
 	extent.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 kthread.9 \
-	malloc.9 md5.9 microtime.9 panic.9 pfind.9 pool.9 printf.9 \
-	psignal.9 ratecheck.9 resettodr.9 \
+	malloc.9 md5.9 microtime.9 panic.9 pfind.9 pool.9 \
+	powerhook_establish.9 printf.9 psignal.9 ratecheck.9 resettodr.9 \
 	random.9 shutdownhook_establish.9 sleep.9 spl.9 store.9 style.9 \
 	time.9 timeout.9 vm_allocate.9 vm_map_copy.9 vm_deallocate.9 \
 	vm_map_inherit.9 vm_map_protect.9
@@ -35,6 +35,7 @@ MLINKS+=pfind.9 pgfind.9
 MLINKS+=pool.9 pool_create.9 pool.9 pool_destroy.9 pool.9 pool_get.9 \
 	pool.9 pool_put.9 pool.9 pool_prime.9 pool.9 pool_sethiwat.9 \
 	pool.9 pool_setlowat.9
+MLINKS+=powerhook_establish.9 powerhook_disestablish.9
 MLINKS+=printf.9 sprintf.9 printf.9 vprintf.9 printf.9 uprintf.9 \
 	printf.9 ttyprintf.9 printf.9 db_printf.9
 MLINKS+=psignal.9 pgsignal.9 psignal.9 gsignal.9
diff --git a/share/man/man9/dopowerhooks.9 b/share/man/man9/dopowerhooks.9
new file mode 100644
index 00000000000..f9961d882c6
--- /dev/null
+++ b/share/man/man9/dopowerhooks.9
@@ -0,0 +1,65 @@
+.\"	$OpenBSD: dopowerhooks.9,v 1.1 2000/07/01 14:45:45 aaron Exp $
+.\"
+.\" Copyright (c) 2000 Aaron Campbell
+.\" All rights reserved.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"      This product includes software developed by Christopher G. Demetriou
+.\"      for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 July 1, 2000
+.Dt DOPOWERHOOKS 9
+.Os
+.Sh NAME
+.Nm dopowerhooks
+.Nd run all power hooks
+.Sh SYNOPSIS
+.Ft void
+.Fn dopowerhooks "int why"
+.Sh DESCRIPTION
+The
+.Fn dopowerhooks
+function invokes all power hooks established using the
+.Xr powerhook_establish 9
+function.
+Power hooks are called in reverse order, i.e., the power hook established
+last will be called first.
+.Pp
+This routine is called from the
+.Xr apm 4
+driver when a power change is detected.
+The
+.Fa why
+argument is one of
+.Dv PWR_SUSPEND ,
+.Dv PWR_STANDBY ,
+or
+.Dv PWR_RESUME ,
+describing the reason for the change in power state.
+Each established power hook is passed this information so the appropriate
+actions can be taken.
+.Sh SEE ALSO
+.Xr apm 4 ,
+.Xr powerhook_establish 9
diff --git a/share/man/man9/powerhook_establish.9 b/share/man/man9/powerhook_establish.9
new file mode 100644
index 00000000000..fc85e196c4d
--- /dev/null
+++ b/share/man/man9/powerhook_establish.9
@@ -0,0 +1,94 @@
+.\"	$OpenBSD: powerhook_establish.9,v 1.1 2000/07/01 14:45:45 aaron Exp $
+.\"
+.\" Copyright (c) 2000 Aaron Campbell
+.\" All rights reserved.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"      This product includes software developed by Christopher G. Demetriou
+.\"      for the NetBSD Project.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 July 1, 2000
+.Dt POWERHOOK_ESTABLISH 9
+.Os
+.Sh NAME
+.Nm powerhook_establish ,
+.Nm powerhook_disestablish
+.Nd add or remove a power hook
+.Sh SYNOPSIS
+.Ft void *
+.Fn powerhook_establish "void (*fn)(void *)" "void *arg"
+.Ft void
+.Fn powerhook_disestablish "void *cookie"
+.Sh DESCRIPTION
+The
+.Fn powerhook_establish
+function adds
+.Fa fn
+to the list of hooks invoked by
+.Xr dopowerhooks 9
+during any change in
+.Xr apm 4
+power state (i.e.,
+during a
+.Dq suspend ,
+.Dq standby ,
+or
+.Dq resume ) .
+When invoked, the hook function
+.Fa fn
+will be passed
+.Fa arg
+as its only argument.
+.Pp
+The
+.Fn powerhook_disestablish
+function removes the hook described by the opaque pointer
+.Fa cookie
+from the list of power hooks.
+If
+.Fa cookie
+is invalid, the result of
+.Fn powerhook_disestablish
+is undefined.
+.Sh RETURN VALUES
+If successful,
+.Fn powerhook_establish
+returns an opaque pointer describing the newly established
+power hook.
+Otherwise, it returns 
+.Dv NULL .
+.Sh EXAMPLES
+It may be appropriate to use a power hook to disestablish interrupts and
+disable PCMCIA functions on PC Cards that are present when the system is put
+into suspend mode.
+The reverse should happen on resume.
+.Pp
+It may be appropriate to use a power hook to halt audio output in a sound
+driver at suspend-time.
+On resume, it may not be possible to recover audio output, but at least the
+device can be put into a known, working state.
+.Sh SEE ALSO
+.Xr apm 4 ,
+.Xr dopowerhooks 9