Add DRIVER_MODULE.9, the manual page describing the kernel driver

declaration macro.
Thanks to Sheldon for a big patch with language/mdoc fixes.

Reviewed by:	asmodai, sheldonh

2 files changed, 100 insertions, 1 deletions

diff --git a/share/man/man9/DRIVER_MODULE.9 b/share/man/man9/DRIVER_MODULE.9
new file mode 100644
index 0000000..ad45ef7
--- /dev/null
+++ b/share/man/man9/DRIVER_MODULE.9
@@ -0,0 +1,99 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2000 Alexander Langer
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 16, 2000
+.Dt DRIVER_MODULE 9
+.Os
+.Sh NAME
+.Nm DRIVER_MODULE
+.Nd kernel driver declaration macro
+.Sh SYNOPSIS
+.Fd #include <sys/bus.h>
+.Fn DRIVER_MODULE "name" "busname" "driver_t driver" "devclass_t devclass" "int (*evh) (struct module *, int, void *)" "void *arg"
+.Sh DESCRIPTION
+The
+.Fn DRIVER_MODULE
+macro declares a kernel driver.
+.Fn DRIVER_MODULE
+expands to the real driver declaration, where the phrase
+.Fa name
+is used as the naming prefix for the driver and its functions.
+Note that it supplied as plain text, and not a
+.Li char
+or
+.Li char * .
+.Pp
+.Fa busname
+is the parent bus of the driver (PCI, ISA, PPBUS and others), e.g.
+.Ql pci ,
+.Ql isa ,
+or
+.Ql ppbus .
+.Pp
+The identifier used in
+.Fn DRIVER_MODULE
+can be different from the driver name.
+Also, the same driver identifier can exist on different busses,
+which is a pretty clean way of making front ends for different cards
+using the same driver on the same or different busses.
+For example, the following is allowed:
+.Pp
+.Fn DRIVERMODULE "foo" "isa" "foo_driver" "foo_devclass" "0" "0" ;
+.Pp
+.Fn DRIVERMODULE "foo" "pci" "foo_driver" "foo_devclass" "0" "0" ;
+.Pp
+.Fa driver
+is the driver of type
+.Li driver_t ,
+which contains the information about the driver and is therefore one of the
+two most important parts of the call to
+.Fn DRIVER_MODULE .
+.Pp
+The
+.Fa devclass
+argument contains the kernel-internal information about the device,
+which will be used wthin the kernel driver module.
+.Pp
+The
+.Fa evh
+argument is the event handler which is called when the driver (or module)
+is loaded or unloaded.
+.Pp
+The
+.Fa arg
+is unused at this time and should be a
+.Dv NULL
+pointer.
+.Sh SEE ALSO
+.Xr driver 9 ,
+.Xr device 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 968cae9..3753e36 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -30,7 +30,7 @@ MAN9+=	device.9 device_add_child.9 device_delete_child.9 device_enable.9 \
 	devclass_get_device.9 devclass_get_devices.9 devclass_get_maxunit.9 \
 	devclass_get_name.9 devclass_get_softc.9 \
 	DEVICE_ATTACH.9 DEVICE_DETACH.9 DEVICE_PROBE.9 DEVICE_SHUTDOWN.9 \
-	BUS_PRINT_CHILD.9 BUS_SETUP_INTR.9 \
+	DRIVER_MODULE.9 BUS_PRINT_CHILD.9 BUS_SETUP_INTR.9 \
 	BUS_READ_IVAR.9 \
 	bus_generic_attach.9 bus_generic_detach.9 bus_generic_map_intr.9 \
 	bus_generic_print_child.9 bus_generic_read_ivar.9 \