[src/trunk]: src/share/man/man4 Add module(4) man page by popular request.

[pgoyette <pgoyette%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3fbe78f8d597
branches:  trunk
changeset: 759557:3fbe78f8d597
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Sun Dec 12 19:29:01 2010 +0000

description:
Add module(4) man page by popular request.

XXX Major portions copied shamelessly from cgd's earlier lkm(4) man page,
XXX so his original copyright/license is retained.

diffstat:

 share/man/man4/Makefile |    4 +-
 share/man/man4/module.4 |  172 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 174 insertions(+), 2 deletions(-)

diffs (194 lines):

diff -r 9f6da75632a9 -r 3fbe78f8d597 share/man/man4/Makefile
--- a/share/man/man4/Makefile   Sun Dec 12 19:04:08 2010 +0000
+++ b/share/man/man4/Makefile   Sun Dec 12 19:29:01 2010 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.537 2010/11/28 01:57:17 christos Exp $
+#      $NetBSD: Makefile,v 1.538 2010/12/12 19:29:01 pgoyette Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -37,7 +37,7 @@
        kloader.4 kse.4 ksyms.4 kttcp.4 \
        lc.4 ld.4 lii.4 lo.4 lxtphy.4 \
        mainbus.4 makphy.4 mbe.4 mca.4 mcclock.4 md.4 mfb.4 mfi.4 mhzc.4 \
-       midi.4 mii.4 mk48txx.4 mlx.4 mly.4 mpls.4 mpt.4 mpu.4 mtd.4 \
+       midi.4 mii.4 mk48txx.4 mlx.4 mly.4 module.4 mpls.4 mpt.4 mpu.4 mtd.4 \
        mtio.4 multicast.4 mvsata.4 \
        nadb.4 ne.4 neo.4 netintro.4 nfe.4 nfsmb.4 njata.4 njs.4 \
        nsclpcsio.4 nside.4 nsp.4 nsphy.4 nsphyter.4 ntwoc.4 null.4 nsmb.4 \
diff -r 9f6da75632a9 -r 3fbe78f8d597 share/man/man4/module.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/module.4   Sun Dec 12 19:29:01 2010 +0000
@@ -0,0 +1,172 @@
+.\" $NetBSD: module.4,v 1.1 2010/12/12 19:29:01 pgoyette Exp $
+.\"
+.\" Copyright (c) 1993 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 for the
+.\"          NetBSD Project.  See http://www.NetBSD.org/ for
+.\"          information about NetBSD.
+.\" 4. 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.
+.\"
+.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
+.\"
+.Dd December 19, 2010
+.Dt MODULE 4
+.Os
+.Sh NAME
+.Nm module
+.Nd Kernel Modules interface
+.Sh SYNOPSIS
+.Cd "options MODULAR"
+.Sh DESCRIPTION
+Kernel modules allow the system administrator to
+dynamically add and remove functionality from a running system.
+This ability also helps software developers to develop
+new parts of the kernel without constantly rebooting to
+test their changes.
+.Pp
+Additionally, the kernel may automatically load software modules as
+needed to perform requested operations.
+For example, an xyzfs module can be loaded automatically when an
+attempt is made to mount an xyzfs filesystem.
+Modules can also depend on other modules, and dependant modules are
+automatically loaded.
+When a module is no longer needed, it can be automatically unloaded.
+.Pp
+An in-kernel linker resolves symbol references between the module
+and the rest of the kernel.
+.Pp
+The
+.Nm
+interface is accessed with the
+.Xr modctl 2
+system call.
+Normally all operations involving
+Kernel Modules are handled by the
+.Xr modload 8 ,
+.Xr modunload 8 ,
+and
+.Xr modstat 8
+programs.
+Users should never have to interact with
+.Xr modctl 2
+directly.
+.Sh MODULE CLASSES
+.Ss Virtual File System modules
+Virtual file systems may be added via the
+.Nm
+interface.
+.Ss Device Driver modules
+New block and character device
+drivers may be loaded into the system with
+.Li "options LKM" .
+One problem with loading a device driver is that the driver's device
+nodes must exist for the devices to be accessed.
+These need to be created manually, after the driver module has been
+successfully loaded.
+.Ss Execution Interpreters
+Execution Interpreters can be loaded to provide support for executing
+binaries not normally supported by kernel.
+This also allows loading
+support for executing foreign system binaries.
+Execution Interpreters may require that an appropriate
+emulation module also be loaded.
+.Ss Miscellaneous modules
+Miscellaneous modules are modules for which there are not currently
+well-defined or well-used interfaces for extension.
+They are provided for extension, and the user-provided module
+initialization routine is expected to install the necessary "hooks"
+into the rest of the operating system.
+An example of a "miscellaneous module" might be a loader for
+card-specific VGA drivers or alternate terminal emulations in
+an appropriately layered console driver.
+.Ss Security-Model modules
+Alternate system security models may loaded using the
+.Nm
+facility.
+.Pp
+.Sh NOTES
+.Ss Security considerations
+Kernel modules can do anything with kernel structures.
+There is no memory protection between modules and the rest of the kernel.
+Hence, a potential attacker with access to the
+.Xr modctl 2
+system call can acquire complete and total control over the system.
+.Pp
+To avoid associated security risks, new modules can only be loaded when
+.Pa securelevel
+is less than or equal to zero, or if the kernel was built with
+.Cd options INSECURE .
+.Ss Module might crash system
+Loading and using a buggy module is likely to crash the operating
+system.
+Since the module becomes part of kernel, a code error is much more
+fatal than for userland programs.
+.Ss Modules need to be updated when the kernel is updated
+Kernel modules are built to operate only with a specific version of the
+Operating System kernel.
+When you update the kernel to a new version, you should also update the
+contents of the
+.Pa /stand/${ARCH}/${VERSION}/modules/
+directory with all required modules.
+(This location has been the subject of much discussion, and may change
+in future versions of the
+.Nx
+operating system.)
+.Ss Missing filesystem modules may prevent the system from booting
+If you attempt to boot the operating system from a filesystem for
+which the module is not built into the kernel, the boot may fail
+with the message
+.Dq "Cannot mount root, error 79" .
+On certain architectures (currently, i386 and amd64), you may be able to
+recover from this error by using the
+.Dq "load xxxfs"
+command before trying to boot.
+This command is only available on newer bootloaders.
+.Pp
+Since the absence of required modules, or the inability of the bootloader
+to load the modules, is a common reason for a
+.Dv MODULAR
+kernel's failure to boot, you might want to maintain a non-MODULAR
+kernel in the root filesystem for recovery purposes.
+.Sh SEE ALSO
+.Xr modctl 2 ,
+.Xr modload 8 ,
+.Xr modstat 8 ,
+.Xr modunload 8 ,
+.Xr module 9
+.Sh HISTORY
+The
+.Nm
+facility was designed to be similar in functionality
+to the loadable kernel modules facility provided by
+.Tn "SunOS 4.1.3" .
+The current
+.Nm
+subsystem was implemented for
+.Nx
+by
+.An Andy Doran
+.Aq ad%netbsd.org@localhost .