Module Name: src
Committed By: pgoyette
Date: Sun Dec 12 19:29:01 UTC 2010
Modified Files:
src/share/man/man4: Makefile
Added Files:
src/share/man/man4: module.4
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.537 -r1.538 src/share/man/man4/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man4/module.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/Makefile
diff -u src/share/man/man4/Makefile:1.537 src/share/man/man4/Makefile:1.538
--- src/share/man/man4/Makefile:1.537 Sun Nov 28 01:57:17 2010
+++ src/share/man/man4/Makefile Sun Dec 12 19:29:01 2010
@@ -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 \
Added files:
Index: src/share/man/man4/module.4
diff -u /dev/null src/share/man/man4/module.4:1.1
--- /dev/null Sun Dec 12 19:29:01 2010
+++ src/share/man/man4/module.4 Sun Dec 12 19:29:01 2010
@@ -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 a...@netbsd.org .
