document the mountroothooks

6 files changed, 186 insertions, 8 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 68df578193f..aac63c912a9 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,16 +1,18 @@
-#	$OpenBSD: Makefile,v 1.84 2004/11/22 04:32:38 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.85 2004/11/28 02:29:16 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.
 
 MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.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 \
+	dohooks.9 dopowerhooks.9 \
+	domountroothooks.9 doshutdownhooks.9 dostartuphooks.9 \
 	evcount.9 extattr.9 file.9 \
 	fork1.9 extent.9 getdevvp.9 getnewvnode.9 hash.9 hashinit.9 \
 	hardclock.9 hook_establish.9 hz.9 hzto.9 iic.9 intro.9 inittodr.9 \
 	kern.9 knote.9 kthread.9 ktrace.9 loadfirmware.9 lock.9 log.9 \
-	malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 namei.9 \
+	malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 \
+	mountroothook_establish.9 namei.9 \
 	panic.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 \
@@ -177,6 +179,7 @@ MLINKS+=printf.9 snprintf.9 printf.9 vsnprintf.9 printf.9 vprintf.9 \
 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+=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 splimp.9 spl.9 spllowersoftclock.9 \
diff --git a/share/man/man9/domountroothooks.9 b/share/man/man9/domountroothooks.9
new file mode 100644
index 00000000000..cfb79e47c89
--- /dev/null
+++ b/share/man/man9/domountroothooks.9
@@ -0,0 +1,71 @@
+.\"	$OpenBSD: domountroothooks.9,v 1.1 2004/11/28 02:29:16 deraadt 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 DOMOUNTROOTHOOKS 9
+.Os
+.Sh NAME
+.Nm domountroothooks
+.Nd run all mountroot hooks
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/systm.h>
+.Ft void
+.Fn domountroothooks "void"
+.Sh DESCRIPTION
+The
+.Fn domountroothooks
+function invokes all mountroot hooks established using the
+.Xr mountroothook_establish 9
+function.
+Mountroot hooks are called in order, i.e.,
+the mountroot 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
+Mountroot hooks are, like shutdown hooks, implemented via the more general
+.Xr dohooks 9
+API.
+.Sh SEE ALSO
+.Xr iop 4 ,
+.Xr ioprbs 4 ,
+.Xr dohooks 9 ,
+.Xr doshutdownhooks 9 ,
+.Xr domountroothooks 9 ,
+.Xr mountroothook_establish 9
diff --git a/share/man/man9/doshutdownhooks.9 b/share/man/man9/doshutdownhooks.9
index 85ef25c0dd6..e3113bcb167 100644
--- a/share/man/man9/doshutdownhooks.9
+++ b/share/man/man9/doshutdownhooks.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: doshutdownhooks.9,v 1.7 2003/08/29 19:46:29 tedu Exp $
+.\"	$OpenBSD: doshutdownhooks.9,v 1.8 2004/11/28 02:29:16 deraadt Exp $
 .\"	$NetBSD: doshutdownhooks.9,v 1.1 1995/11/25 21:24:49 perry Exp $
 .\"
 .\" Copyright (c) 1994 Christopher G. Demetriou
@@ -64,4 +64,5 @@ API.
 .Xr boot 9 ,
 .Xr dohooks 9 ,
 .Xr dostartuphooks 9 ,
+.Xr domountroothooks 9 ,
 .Xr shutdownhook_establish 9
diff --git a/share/man/man9/dostartuphooks.9 b/share/man/man9/dostartuphooks.9
index 4a5e1647123..b2148297781 100644
--- a/share/man/man9/dostartuphooks.9
+++ b/share/man/man9/dostartuphooks.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: dostartuphooks.9,v 1.5 2003/08/29 19:46:29 tedu Exp $
+.\"	$OpenBSD: dostartuphooks.9,v 1.6 2004/11/28 02:29:16 deraadt Exp $
 .\"
 .\" Copyright (c) 2001 Niklas Hallqvist.
 .\" All rights reserved.
@@ -67,4 +67,5 @@ API.
 .Xr ioprbs 4 ,
 .Xr dohooks 9 ,
 .Xr doshutdownhooks 9 ,
+.Xr domountroothooks 9 ,
 .Xr startuphook_establish 9
diff --git a/share/man/man9/hook_establish.9 b/share/man/man9/hook_establish.9
index 71abca6cfb3..8f9c541ecf4 100644
--- a/share/man/man9/hook_establish.9
+++ b/share/man/man9/hook_establish.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: hook_establish.9,v 1.6 2003/08/29 19:46:29 tedu Exp $
+.\"	$OpenBSD: hook_establish.9,v 1.7 2004/11/28 02:29:16 deraadt Exp $
 .\"
 .\" Copyright (c) 2001 Niklas Hallqvist.
 .\" All rights reserved.
@@ -74,7 +74,7 @@ is invalid, the result of
 .Fn hook_disestablish
 is undefined.
 .Pp
-Both the startup- and shutdownhooks systems use this API for their
+The startup-, mountroot, and shutdownhooks systems use this API for their
 implementation.
 .Sh RETURN VALUES
 If successful,
@@ -88,4 +88,6 @@ Otherwise, it returns
 .Xr doshutdownhooks 9 ,
 .Xr dostartuphooks 9 ,
 .Xr shutdownhook_establish 9 ,
-.Xr startuphook_establish 9
+.Xr startuphook_establish 9 ,
+.Xr mountroothook_establish 9
+
diff --git a/share/man/man9/mountroothook_establish.9 b/share/man/man9/mountroothook_establish.9
new file mode 100644
index 00000000000..6b156a47969
--- /dev/null
+++ b/share/man/man9/mountroothook_establish.9
@@ -0,0 +1,100 @@
+.\"	$OpenBSD: mountroothook_establish.9,v 1.1 2004/11/28 02:29:16 deraadt Exp $
+.\"	$NetBSD: mountroothook_establish.9,v 1.1 1995/11/25 21:24:52 perry Exp $
+.\"
+.\" Copyright (c) 1994 Christopher G. Demetriou
+.\" 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 November 13, 1995
+.Dt MOUNTROOTHOOK_ESTABLISH 9
+.Os
+.Sh NAME
+.Nm mountroothook_establish ,
+.Nm mountroothook_disestablish
+.Nd add or remove a mountroot hook
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/systm.h>
+.Ft void *
+.Fn mountroothook_establish "void (*fn)(void *)" "void *arg"
+.Ft void
+.Fn mountroothook_disestablish "void *cookie"
+.Sh DESCRIPTION
+The
+.Fn mountroothook_establish
+function adds
+.Fa fn
+to the list of hooks invoked by
+.Xr domountroothooks 9
+at mountroot.
+When invoked, the hook function
+.Fa fn
+will be passed
+.Fa arg
+as its only argument.
+.Pp
+The
+.Fn mountroothook_disestablish
+function removes the hook described by the opaque pointer
+.Fa cookie
+from the list of hooks to be invoked at mountroot.
+If
+.Fa cookie
+is invalid, the result of
+.Fn mountroothook_disestablish
+is undefined.
+.Pp
+Mountroot hooks should be used to perform one-time activities
+that must happen immediately after the root filesystem has been
+mounted by the kernel, but before
+.Xr init 8
+has been started.
+.Pp
+Mountroot hooks are, like startup hooks, implemented via the more general
+.Xr dohooks 9
+API.
+.Sh RETURN VALUES
+If successful,
+.Fn mountroothook_establish
+returns an opaque pointer describing the newly established
+mountroot hook.
+Otherwise, it returns
+.Dv NULL .
+.Sh EXAMPLES
+It may be appropriate to use a mountroot hook to
+split the attach function of a device driver.
+Once the root filesystem is mounted, the hook will be called
+and it is safe to use
+.Xr loadfirmware 9
+to get the firmware out of the filesystem.
+.Sh SEE ALSO
+.Xr dohooks 9 ,
+.Xr domountroothooks 9 ,
+.Xr dostartuphooks 9
+.Sh BUGS
+The names are clumsy, at best.