Startup hooks. Can be used for providing root/swap devices from device

systems which want configuration to finish late, like I2O.  Implemented via
a general hooks mechanism which the shutdown hooks have been converted to
use as well.  It even has manpages!

7 files changed, 334 insertions, 11 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index b56cf2be542..ab6ef683fcf 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,16 +1,20 @@
-#	$OpenBSD: Makefile,v 1.40 2001/07/16 20:54:58 krw Exp $
+#	$OpenBSD: Makefile,v 1.41 2001/07/27 09:55:07 niklas 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=	altq.9 audio.9 boot.9 bus_dma.9 bus_space.9 \
-	copy.9 crypto.9 ctxsw.9 disk.9 disklabel.9 \
-	dopowerhooks.9 doshutdownhooks.9 fetch.9 fork1.9 \
-	extent.9 hardclock.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 kthread.9 \
-	malloc.9 mbuf_tags.9 md5.9 microtime.9 panic.9 pfind.9 physio.9 \
+MAN=	altq.9 audio.9 boot.9 bus_dma.9 bus_space.9 copy.9 crypto.9 ctxsw.9 \
+	disk.9 disklabel.9 \
+	dohooks.9 dopowerhooks.9 doshutdownhooks.9 dostartuphooks.9 \
+	fetch.9 fork1.9 extent.9 \
+	hardclock.9 hook_establish.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 \
+	kthread.9 malloc.9 mbuf_tags.9 md5.9 microtime.9 \
+	panic.9 pfind.9 physio.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.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 uvm.9 \
+	ratecheck.9 resettodr.9 random.9 \
+	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
+	store.9 style.9 \
+	time.9 timeout.9 uvm.9 \
 	vm_allocate.9 vm_map_copy.9 vm_deallocate.9 \
 	vm_map_inherit.9 vm_map_protect.9 vnode.9 vn_lock.9 \
 	vwaitforio.9 vwaitforio.9
@@ -63,6 +67,7 @@ MLINKS+=extent.9 extent_create.9 extent.9 extent_destroy.9 \
 	extent.9 extent_free.9 extent.9 extent_print.9
 MLINKS+=fetch.9 fubyte.9 fetch.9 fuibyte.9 fetch.9 fusword.9 \
 	fetch.9 fuswintr.9 fetch.9 fuword.9 fetch.9 fuiword.9
+MLINKS+=hook_establish.9 hook_disestablish.9
 MLINKS+=hz.9 tick.9 hz.9 tickadj.9 hz.9 stathz.9 hz.9 profhz.9
 MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9 \
 	kthread.9 kthread_create_deferred.9
@@ -82,6 +87,7 @@ MLINKS+=spl.9 spl0.9 spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 \
 	spl.9 splimp.9 spl.9 splnet.9 spl.9 splsched.9 spl.9 splserial.9 \
 	spl.9 splsoftclock.9 spl.9 splsoftnet.9 spl.9 splsoftserial.9 \
 	spl.9 splstatclock.9 spl.9 spltty.9 spl.9 splx.9
+MLINKS+=startuphook_establish.9 startuphook_disestablish.9
 MLINKS+=store.9 subyte.9 store.9 suibyte.9 store.9 susword.9 \
 	store.9 suswintr.9 store.9 suword.9 store.9 suiword.9
 MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9
diff --git a/share/man/man9/dohooks.9 b/share/man/man9/dohooks.9
new file mode 100644
index 00000000000..5d5aad36b1d
--- /dev/null
+++ b/share/man/man9/dohooks.9
@@ -0,0 +1,60 @@
+.\"	$OpenBSD: dohooks.9,v 1.1 2001/07/27 09:55:07 niklas Exp $
+.\"
+.\" Copyright (c) 2001 Niklas Hallqvist.
+.\" 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. 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 27, 2001
+.Dt DOHOOKS 9
+.Os
+.Sh NAME
+.Nm dohooks
+.Nd run all hooks in a list
+.Sh SYNOPSIS
+.Fd #include <sys/systm.h>
+.Ft void
+.Fn dohooks "struct hook_desc_head *head"
+.Sh DESCRIPTION
+The
+.Fn dohooks
+function invokes all hooks established using the
+.Xr hook_establish 9
+function.
+Hooks are called in the order of the the TAILQ that
+.Fa head
+points to, however
+.Xr hook_establish 9
+can put the hooks either at the head or the tail of that queue,
+making it possible to call the hooks either in the order of
+establishment, or its reverse.
+.Pp
+This function is used to implement the
+.Xr doshutdownhooks 9
+as well as the
+.Xr dostartuphooks 9
+macros.
+.Sh SEE ALSO
+.Xr doshutdownhooks 9 ,
+.Xr dostartuphooks 9 ,
+.Xr hook_establish 9
diff --git a/share/man/man9/doshutdownhooks.9 b/share/man/man9/doshutdownhooks.9
index 6c241847d59..19be7e1575c 100644
--- a/share/man/man9/doshutdownhooks.9
+++ b/share/man/man9/doshutdownhooks.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: doshutdownhooks.9,v 1.5 2001/03/09 14:04:19 aaron Exp $
+.\"	$OpenBSD: doshutdownhooks.9,v 1.6 2001/07/27 09:55:07 niklas Exp $
 .\"	$NetBSD: doshutdownhooks.9,v 1.1 1995/11/25 21:24:49 perry Exp $
 .\"
 .\" Copyright (c) 1994 Christopher G. Demetriou
@@ -54,6 +54,12 @@ with interrupts turned off.
 It is called immediately before the system is halted or rebooted,
 after file systems have been unmounted, after the clock has been updated,
 and after a system dump has been done (if necessary).
+.Pp
+Shutdown hooks are, like startup hooks, implemented via the more general
+.Xr dohooks 9
+API.
 .Sh SEE ALSO
 .Xr boot 9 ,
+.Xr dohooks 9 ,
+.Xr dostartuphooks 9 ,
 .Xr shutdownhook_establish 9
diff --git a/share/man/man9/dostartuphooks.9 b/share/man/man9/dostartuphooks.9
new file mode 100644
index 00000000000..1cd6834ecea
--- /dev/null
+++ b/share/man/man9/dostartuphooks.9
@@ -0,0 +1,67 @@
+.\"	$OpenBSD: dostartuphooks.9,v 1.1 2001/07/27 09:55:07 niklas Exp $
+.\"
+.\" Copyright (c) 2001 Niklas Hallqvist.
+.\" 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. 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 27 2001
+.Dt DOSTARTUPHOOKS 9
+.Os
+.Sh NAME
+.Nm dostartuphooks
+.Nd run all startup hooks
+.Sh SYNOPSIS
+.Ft void
+.Fn dostartuphooks "void"
+.Sh DESCRIPTION
+The
+.Fn dostartuphooks
+function invokes all startup hooks established using the
+.Xr startuphook_establish 9
+function.
+Startup hooks are called in order, i.e.,
+the startup hook established first will be called first.
+.Pp
+This function is called from
+.Fn main
+with interrupts turned on.
+It is called immediately before the system configures its root and swap
+devices, but fully after all normal autoconfiguration.  This can be used
+to let device subsystems needing delayed configuration (e.g., due to very long
+initialization times) still provide the root device.  The
+I2O system, implemented by the
+.Xr iop 4
+and
+.Xr ioprbs 4
+drivers, is a good example.
+.Pp
+Startup hooks are, like shutdown hooks, implemented via the more general
+.Xr dohooks 9
+API.
+.Sh SEE ALSO
+.Xr dohooks 4 ,
+.Xr doshutdownhooks 4 ,
+.Xr iop 4 ,
+.Xr ioprbs 4 ,
+.Xr startuphook_establish 9
diff --git a/share/man/man9/hook_establish.9 b/share/man/man9/hook_establish.9
new file mode 100644
index 00000000000..0b09fcb3a42
--- /dev/null
+++ b/share/man/man9/hook_establish.9
@@ -0,0 +1,89 @@
+.\"	$OpenBSD: hook_establish.9,v 1.1 2001/07/27 09:55:07 niklas Exp $
+.\"
+.\" Copyright (c) 2001 Niklas Hallqvist.
+.\" 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. 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 27 2001
+.Dt HOOK_ESTABLISH 9
+.Os
+.Sh NAME
+.Nm hook_establish ,
+.Nm hook_disestablish
+.Nd add or remove a hook from a specified list of such
+.Sh SYNOPSIS
+.Fd #include <sys/systm.h>
+.Ft void *
+.Fn hook_establish "struct hook_desc_head *head" "int tail" "void (*fn)(void *)" "void *arg"
+.Ft void
+.Fn hook_disestablish "struct hook_desc_head *head" "void *cookie"
+.Sh DESCRIPTION
+The
+.Fn hook_establish
+function adds
+.Fa fn
+to the list of hooks invoked by
+.Xr dohooks 9 .
+If
+.Fa tail
+is non-zero, the hook is added to the tail of the list
+denoted by the TAILQ_HEAD pointer
+.Fa head ,
+otherwise to the front.  The
+.Xr dohooks 9
+function will at its invocation call each hook from the front of this
+list.
+When invoked, the hook function
+.Fa fn
+will be passed
+.Fa arg
+as its only argument.
+.Pp
+The
+.Fn hook_disestablish
+function removes the hook described by the opaque pointer
+.Fa cookie
+from the list of hooks denoted by the TAILQ_HEAD pointer
+.Fa head .
+If
+.Fa cookie
+is invalid, the result of
+.Fn hook_disestablish
+is undefined.
+.Pp
+Both the startup- and shutdownhooks systems uses this API for their
+implementation.
+.Sh RETURN VALUES
+If successful,
+.Fn hook_establish
+returns an opaque pointer describing the newly established
+hook.
+Otherwise, it returns
+.Dv NULL .
+.Sh SEE ALSO
+.Xr dohooks 9 ,
+.Xr doshutdownhooks 9 ,
+.Xr dostartuphooks 9 ,
+.Xr shutdownhook_establish 9 ,
+.Xr startuphook_establish 9
diff --git a/share/man/man9/shutdownhook_establish.9 b/share/man/man9/shutdownhook_establish.9
index 321d8edf526..febb8334f3b 100644
--- a/share/man/man9/shutdownhook_establish.9
+++ b/share/man/man9/shutdownhook_establish.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: shutdownhook_establish.9,v 1.9 2000/10/12 18:06:02 aaron Exp $
+.\"	$OpenBSD: shutdownhook_establish.9,v 1.10 2001/07/27 09:55:07 niklas Exp $
 .\"	$NetBSD: shutdownhook_establish.9,v 1.1 1995/11/25 21:24:52 perry Exp $
 .\"
 .\" Copyright (c) 1994 Christopher G. Demetriou
@@ -73,6 +73,10 @@ Because of the environment in which they are run, shutdown hooks cannot
 rely on many system services (including file systems, timeouts,
 and other interrupt-driven services) or even basic system
 integrity (because the system could be rebooting after a crash).
+.Pp
+Shutdown hooks are, like startup hooks, implemented via the more general
+.Xr dohooks 9
+API.
 .Sh RETURN VALUES
 If successful,
 .Fn shutdownhook_establish
@@ -90,6 +94,8 @@ It may be appropriate to use a shutdown hook to
 inform watchdog timer hardware that the operating system
 is no longer running.
 .Sh SEE ALSO
-.Xr doshutdownhooks 9
+.Xr dohooks 9 ,
+.Xr doshutdownhooks 9 ,
+.Xr dostartuphooks 9
 .Sh BUGS
 The names are clumsy, at best.
diff --git a/share/man/man9/startuphook_establish.9 b/share/man/man9/startuphook_establish.9
new file mode 100644
index 00000000000..a8b76bb06d9
--- /dev/null
+++ b/share/man/man9/startuphook_establish.9
@@ -0,0 +1,89 @@
+.\"	$OpenBSD: startuphook_establish.9,v 1.1 2001/07/27 09:55:07 niklas Exp $
+.\"
+.\" Copyright (c) 1995 Niklas Hallqvist.
+.\" 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. 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 27 2001
+.Dt STARTUPHOOK_ESTABLISH 9
+.Os
+.Sh NAME
+.Nm startuphook_establish ,
+.Nm startuphook_disestablish
+.Nd add or remove a startup hook
+.Sh SYNOPSIS
+.Ft void *
+.Fn startuphook_establish "void (*fn)(void *)" "void *arg"
+.Ft void
+.Fn startuphook_disestablish "void *cookie"
+.Sh DESCRIPTION
+The
+.Fn startuphook_establish
+function adds
+.Fa fn
+to the list of hooks invoked by
+.Xr dostartuphooks 9
+at startup.
+When invoked, the hook function
+.Fa fn
+will be passed
+.Fa arg
+as its only argument.
+.Pp
+The
+.Fn startuphook_disestablish
+function removes the hook described by the opaque pointer
+.Fa cookie
+from the list of hooks to be invoked at startup.
+If
+.Fa cookie
+is invalid, the result of
+.Fn startuphook_disestablish
+is undefined.
+.Pp
+Startup hooks should be used to perform one-time activities
+that must happen immediately before the root and swap devices
+are configured, but after normal device autoconfiguration.
+.Pp
+Startup hooks are, like shutdown hooks, implemented via the more general
+.Xr dohooks 9
+API.
+.Sh RETURN VALUES
+If successful,
+.Fn startuphook_establish
+returns an opaque pointer describing the newly established
+startup hook.
+Otherwise, it returns
+.Dv NULL .
+.Sh EXAMPLES
+It may be appropriate to use a startup hook to provide potential root or
+swap devices that have delayed configuration.  The
+.Xr iop 4
+shows an example of this usage.
+.Sh SEE ALSO
+.Xr dohooks 9 ,
+.Xr doshutdownhooks 9 ,
+.Xr dostartuphooks 9
+.Sh BUGS
+The names are clumsy, at best.