From 988a1851d762845cfd02bf7667730c55b9a14a32 Mon Sep 17 00:00:00 2001
From: John Baldwin <jhb@FreeBSD.org>
Date: Tue, 21 Aug 2012 17:58:39 +0000
Subject: [PATCH] Document DRIVER_MODULE_ORDERED, EARLY_DRIVER_MODULE, and
 EARLY_DRIVER_MODULE_ORDERED.

---
 share/man/man9/DRIVER_MODULE.9 | 52 ++++++++++++++++++++++++++++++++--
 share/man/man9/Makefile        |  3 ++
 2 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/share/man/man9/DRIVER_MODULE.9 b/share/man/man9/DRIVER_MODULE.9
index ca739452b366..274fdcceed99 100644
--- a/share/man/man9/DRIVER_MODULE.9
+++ b/share/man/man9/DRIVER_MODULE.9
@@ -28,11 +28,14 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 27, 2011
+.Dd August 21, 2012
 .Dt DRIVER_MODULE 9
 .Os
 .Sh NAME
-.Nm DRIVER_MODULE
+.Nm DRIVER_MODULE ,
+.Nm DRIVER_MODULE_ORDERED ,
+.Nm EARLY_DRIVER_MODULE ,
+.Nm EARLY_DRIVER_MODULE_ORDERED
 .Nd kernel driver declaration macro
 .Sh SYNOPSIS
 .In sys/param.h
@@ -40,6 +43,9 @@
 .In sys/bus.h
 .In sys/module.h
 .Fn DRIVER_MODULE name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg"
+.Fn DRIVER_MODULE_ORDERED name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" "int order"
+.Fn EARLY_DRIVER_MODULE name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" "enum sysinit_elem_order order" "int pass"
+.Fn EARLY_DRIVER_MODULE_ORDERED name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" "enum sysinit_elem_order order" "int pass"
 .Sh DESCRIPTION
 The
 .Fn DRIVER_MODULE
@@ -95,10 +101,50 @@ The
 is unused at this time and should be a
 .Dv NULL
 pointer.
+.Pp
+The
+.Fn DRIVER_MODULE_ORDERED
+macro allows a driver to be registered in a specific order.
+This can be useful if a single kernel module contains multiple drivers
+that are inter-dependent.
+The
+.Fa order
+argument should be one of the
+.Xr SYSINIT 9
+initialization ordering constants
+.Pq Dv SI_ORDER_* .
+The default order for a driver module is
+.Dv SI_ORDER_MIDDLE .
+Typically a module will specify an order of
+.Dv SI_ORDER_ANY
+for a single driver to ensure it is registered last.
+.Pp
+The
+.Fn EARLY_DRIVER_MODULE
+macro allows a driver to be registered for a specific pass level.
+The boot time probe and attach process makes multiple passes over the
+device tree.
+Certain critical drivers that provide basic services needed by other
+devices are attach during earlier passes.
+Most drivers are attached in a final general pass.
+A driver that attaches during an early pass must register for a specific
+pass level
+.Pq BUS_PASS_*
+via the
+.Fa pass
+argument.
+Once a driver is registered it is available to attach to devices for
+all subsequent passes.
+.Pp
+The
+.Fn EARLY_DRIVER_MODULE_ORDERED
+macro allows a driver to be registered both in a specific order and
+for a specific pass level.
 .Sh SEE ALSO
 .Xr device 9 ,
 .Xr driver 9 ,
-.Xr module 9
+.Xr module 9 ,
+.Xr SYSINIT 9
 .Sh AUTHORS
 This manual page was written by
 .An Alexander Langer Aq alex@FreeBSD.org .
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 06b0e33e70d5..373da0bf25a7 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -628,6 +628,9 @@ MLINKS+=drbr.9 drbr_free.9 \
 	drbr.9 drbr_empty.9 \
 	drbr.9 drbr_inuse.9 \
 	drbr.9 drbr_stats_update.9
+MLINKS+=DRIVER_MODULE.9 DRIVER_MODULE_ORDERED.9 \
+	DRIVER_MODULE.9 EARLY_DRIVER_MODULE.9 \
+	DRIVER_MODULE.9 EARLY_DRIVER_MODULE_ORDERED.9
 MLINKS+=EVENTHANDLER.9 EVENTHANDLER_DECLARE.9 \
 	EVENTHANDLER.9 EVENTHANDLER_DEREGISTER.9 \
 	EVENTHANDLER.9 eventhandler_deregister.9 \