Module Name: src
Committed By: jruoho
Date: Tue Dec 14 16:18:16 UTC 2010
Modified Files:
src/distrib/sets/lists/man: mi
src/share/man/man4: Makefile
src/share/man/man7: Makefile intro.7
Added Files:
src/share/man/man7: module.7
Removed Files:
src/share/man/man4: module.4
Log Message:
By majority vote, move module(4) to the section 7.
To generate a diff of this commit:
cvs rdiff -u -r1.1267 -r1.1268 src/distrib/sets/lists/man/mi
cvs rdiff -u -r1.538 -r1.539 src/share/man/man4/Makefile
cvs rdiff -u -r1.5 -r0 src/share/man/man4/module.4
cvs rdiff -u -r1.25 -r1.26 src/share/man/man7/Makefile
cvs rdiff -u -r1.17 -r1.18 src/share/man/man7/intro.7
cvs rdiff -u -r0 -r1.1 src/share/man/man7/module.7
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/man/mi
diff -u src/distrib/sets/lists/man/mi:1.1267 src/distrib/sets/lists/man/mi:1.1268
--- src/distrib/sets/lists/man/mi:1.1267 Mon Dec 13 19:36:34 2010
+++ src/distrib/sets/lists/man/mi Tue Dec 14 16:18:16 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1267 2010/12/13 19:36:34 pooka Exp $
+# $NetBSD: mi,v 1.1268 2010/12/14 16:18:16 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -1241,7 +1241,7 @@
./usr/share/man/cat4/mk48txx.0 man-sys-catman .cat
./usr/share/man/cat4/mlx.0 man-sys-catman .cat
./usr/share/man/cat4/mly.0 man-sys-catman .cat
-./usr/share/man/cat4/module.0 man-sys-catman .cat
+./usr/share/man/cat4/module.0 man-obsolete obsolete
./usr/share/man/cat4/mpls.0 man-sys-catman .cat
./usr/share/man/cat4/mpt.0 man-sys-catman .cat
./usr/share/man/cat4/mpu.0 man-sys-catman .cat
@@ -1979,6 +1979,7 @@
./usr/share/man/cat7/mandoc.0 man-obsolete obsolete
./usr/share/man/cat7/mdoc.0 man-groff-catman .cat,groff
./usr/share/man/cat7/miscellaneous.0 man-obsolete obsolete
+./usr/share/man/cat7/module.0 man-reference-catman .cat
./usr/share/man/cat7/msafer.0 man-obsolete obsolete
./usr/share/man/cat7/nls.0 man-reference-catman .cat
./usr/share/man/cat7/orders.0 man-reference-catman .cat
@@ -3923,7 +3924,7 @@
./usr/share/man/html4/mk48txx.html man-sys-htmlman html
./usr/share/man/html4/mlx.html man-sys-htmlman html
./usr/share/man/html4/mly.html man-sys-htmlman html
-./usr/share/man/html4/module.html man-sys-htmlman html
+./usr/share/man/html4/module.html man-obsolete obsolete
./usr/share/man/html4/mpls.html man-sys-htmlman html
./usr/share/man/html4/mpt.html man-sys-htmlman html
./usr/share/man/html4/mpu.html man-sys-htmlman html
@@ -4599,6 +4600,7 @@
./usr/share/man/html7/lint.html man-reference-htmlman html
./usr/share/man/html7/mailaddr.html man-reference-htmlman html
./usr/share/man/html7/mdoc.html man-groff-htmlman html,groff
+./usr/share/man/html7/module.html man-reference-htmlman html
./usr/share/man/html7/nls.html man-reference-htmlman html
./usr/share/man/html7/orders.html man-reference-htmlman html
./usr/share/man/html7/pcap-filter.html man-netutil-htmlman html
@@ -6461,7 +6463,7 @@
./usr/share/man/man4/mk48txx.4 man-sys-man .man
./usr/share/man/man4/mlx.4 man-sys-man .man
./usr/share/man/man4/mly.4 man-sys-man .man
-./usr/share/man/man4/module.4 man-sys-man .man
+./usr/share/man/man4/module.4 man-obsolete obsolete
./usr/share/man/man4/mpls.4 man-sys-man .man
./usr/share/man/man4/mpt.4 man-sys-man .man
./usr/share/man/man4/mpu.4 man-sys-man .man
@@ -7198,6 +7200,7 @@
./usr/share/man/man7/mailaddr.7 man-reference-man .man
./usr/share/man/man7/mandoc.7 man-obsolete obsolete
./usr/share/man/man7/mdoc.7 man-groff-man .man,groff
+./usr/share/man/man7/module.7 man-reference-man .man
./usr/share/man/man7/msafer.7 man-obsolete obsolete
./usr/share/man/man7/nls.7 man-reference-man .man
./usr/share/man/man7/orders.7 man-reference-man .man
Index: src/share/man/man4/Makefile
diff -u src/share/man/man4/Makefile:1.538 src/share/man/man4/Makefile:1.539
--- src/share/man/man4/Makefile:1.538 Sun Dec 12 19:29:01 2010
+++ src/share/man/man4/Makefile Tue Dec 14 16:18:15 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.538 2010/12/12 19:29:01 pgoyette Exp $
+# $NetBSD: Makefile,v 1.539 2010/12/14 16:18:15 jruoho 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 module.4 mpls.4 mpt.4 mpu.4 mtd.4 \
+ midi.4 mii.4 mk48txx.4 mlx.4 mly.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 \
Index: src/share/man/man7/Makefile
diff -u src/share/man/man7/Makefile:1.25 src/share/man/man7/Makefile:1.26
--- src/share/man/man7/Makefile:1.25 Tue Nov 30 20:59:10 2010
+++ src/share/man/man7/Makefile Tue Dec 14 16:18:15 2010
@@ -1,10 +1,10 @@
-# $NetBSD: Makefile,v 1.25 2010/11/30 20:59:10 jruoho Exp $
+# $NetBSD: Makefile,v 1.26 2010/12/14 16:18:15 jruoho Exp $
# @(#)Makefile 8.1 (Berkeley) 6/5/93
# missing: eqnchar.7 man.7 ms.7 term.7
MAN= ascii.7 c.7 environ.7 glob.7 hier.7 hostname.7 intro.7 mailaddr.7 \
- nls.7 operator.7 orders.7 pkgsrc.7 release.7 \
+ module.7 nls.7 operator.7 orders.7 pkgsrc.7 release.7 \
script.7 setuid.7 signal.7 sticky.7 symlink.7 sysctl.7 \
tests.7
Index: src/share/man/man7/intro.7
diff -u src/share/man/man7/intro.7:1.17 src/share/man/man7/intro.7:1.18
--- src/share/man/man7/intro.7:1.17 Tue Nov 30 21:22:38 2010
+++ src/share/man/man7/intro.7 Tue Dec 14 16:18:15 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: intro.7,v 1.17 2010/11/30 21:22:38 jruoho Exp $
+.\" $NetBSD: intro.7,v 1.18 2010/12/14 16:18:15 jruoho Exp $
.\"
.\" Copyright (c) 1983, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -29,7 +29,7 @@
.\"
.\" @(#)intro.7 8.1 (Berkeley) 6/5/93
.\"
-.Dd November 30, 2010
+.Dd December 14, 2010
.Dt INTRO 7
.Os
.Sh NAME
@@ -70,6 +70,8 @@
.\" macros for formatting papers
.\" .It Sy \&ms
.\" macros for formatting manuscripts
+.It Xr module 7
+kernel modules
.It Xr nls 7
overview of national language support
.It Xr operator 7
Added files:
Index: src/share/man/man7/module.7
diff -u /dev/null src/share/man/man7/module.7:1.1
--- /dev/null Tue Dec 14 16:18:16 2010
+++ src/share/man/man7/module.7 Tue Dec 14 16:18:15 2010
@@ -0,0 +1,212 @@
+.\" $NetBSD: module.7,v 1.1 2010/12/14 16:18:15 jruoho 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 14, 2010
+.Dt MODULE 7
+.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
+.Dq xyzfs
+module can be loaded automatically when an
+attempt is made to mount an
+.Dq xyzfs
+file system.
+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.
+All common 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
+Many device drivers can be loaded as a kernel module.
+One potential problem specific to block and character device drivers
+is that the device nodes must exist for the devices to be accessed.
+These need to be created manually, after the driver module has been
+successfully loaded.
+The majority of the device driver modules however does not
+need any manual intervention to function properly.
+.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.
+.Sh EXAMPLES
+The common build tool of
+.Nx ,
+.Dq build.sh ,
+automatically compiles and installs all
+modules during a full system build and install.
+Sometimes it is however useful to update only modules.
+The following example demonstrates one way to do this.
+It is assumed that the source code is under
+.Pa /usr/src ,
+while the object and toolchain directories are under
+.Pa /usr/obj
+and
+.Pa /usr/tools ,
+respectively.
+.Bd -literal -offset indent
+cd /usr/src/sys/modules
+
+export OBJDIR=/usr/obj
+export TOOLDIR=/usr/tools
+
+make clean
+make
+make install
+.Ed
+.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 old
+.Dv LKM
+interface was replaced by
+.Nm
+in
+.Nx 5.0 .
+.Sh AUTHORS
+The
+.Nm
+subsystem was implemented by
+.An Andrew Doran
+.Aq a...@netbsd.org .
+.Sh CAVEATS
+The
+.Nm
+framework is still under active development.
+At least two potential caveats can be mentioned.
+.Bl -enum -offset 2n
+.It
+Kernel modules are built to operate only with a specific version of the
+.Nx
+kernel.
+When the kernel is updated to a new version, the contents of the
+.Pa /stand/${ARCH}/${VERSION}/modules/
+directory should be updated as well.
+(This location has been the subject of much discussion, and may change
+in future versions of
+.Nx . )
+.It
+If an attempt is made to boot the operating system from a file system 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), one 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.
+.El
+.Pp
+The absence of required modules or the inability of the bootloader
+to load the modules are common reasons for failures to boot a
+.Cd MODULAR
+kernel.
+It may be a good practice to maintain a non-MODULAR kernel
+in the root file system for recovery purposes.
+.Sh SECURITY CONSIDERATIONS
+A module becomes part of the kernel once loaded.
+Compared to userland programs, all errors in the code can be fatal.
+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 .
+Refer to
+.Xr secmodel_securelevel 9
+for additional details on the
+.Pa securelevel .
+Only use modules from trusted sources.
