[src/trunk]: src/share/man/man4 Clarifications. Improvements to wording and m...

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

details:   https://anonhg.NetBSD.org/src/rev/89365791adbf
branches:  trunk
changeset: 759609:89365791adbf
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Mon Dec 13 19:22:01 2010 +0000

description:
Clarifications. Improvements to wording and markup. Also follow the common
conventions and split the NOTES into CAVEATS (all these really highlight the
work-in-progress nature of the modules). Split the note about security into
SECURITY CONSIDERATIONS. Add an EXAMPLE on how to manually update modules.

diffstat:

 share/man/man4/module.4 |  159 ++++++++++++++++++++++++++++++-----------------
 1 files changed, 100 insertions(+), 59 deletions(-)

diffs (210 lines):

diff -r 9942a2bcbf5e -r 89365791adbf share/man/man4/module.4
--- a/share/man/man4/module.4   Mon Dec 13 19:19:10 2010 +0000
+++ b/share/man/man4/module.4   Mon Dec 13 19:22:01 2010 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: module.4,v 1.3 2010/12/12 22:14:19 pgoyette Exp $
+.\" $NetBSD: module.4,v 1.4 2010/12/13 19:22:01 jruoho Exp $
 .\"
 .\" Copyright (c) 1993 Christopher G. Demetriou
 .\" All rights reserved.
@@ -32,7 +32,7 @@
 .\"
 .\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
 .\"
-.Dd December 19, 2010
+.Dd December 13, 2010
 .Dt MODULE 4
 .Os
 .Sh NAME
@@ -49,8 +49,12 @@
 .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 file system.
+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.
@@ -63,8 +67,8 @@
 interface is accessed with the
 .Xr modctl 2
 system call.
-Normally all operations involving
-Kernel Modules are handled by the
+All common operations involving
+kernel modules are handled by the
 .Xr modload 8 ,
 .Xr modunload 8 ,
 and
@@ -79,13 +83,13 @@
 .Nm
 interface.
 .Ss Device Driver modules
-New block and character device
-drivers may be loaded into the system with
-.Li "options MODULAR" .
-One problem with loading a device driver is that the driver's device
-nodes must exist for the devices to be accessed.
+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.
+Majority of the device driver modules do not however
+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.
@@ -106,50 +110,31 @@
 Alternate system security models may loaded using the
 .Nm
 facility.
-.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 file system modules may prevent the system from booting
-If you attempt 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), 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 file system for recovery purposes.
+.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 ,
@@ -162,10 +147,66 @@
 facility was designed to be similar in functionality
 to the loadable kernel modules facility provided by
 .Tn "SunOS 4.1.3" .
-The current
+The old
+.Dv LKM
+interface was replaced by
 .Nm
-subsystem was implemented for
-.Nx
-by
+in
+.Nx 5.0 .
+.Sh AUTHORS
+The
+.Nm
+subsystem was implemented by
 .An Andrew Doran
 .Aq ad%netbsd.org@localhost .
+.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.