Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
pgoyette 2010-12-12 19:29:01 +00:00
parent e8465113ee
commit bded1272a7
2 changed files with 174 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
share/man/man4/Makefile
View File

@ -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 @@ MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
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 \

172
share/man/man4/module.4 Normal file
View File

@ -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 .