[src/trunk]: src/share/man/man9 A few corrections:

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

details:   https://anonhg.NetBSD.org/src/rev/54d271e89a71
branches:  trunk
changeset: 757162:54d271e89a71
user:      jnemeth <jnemeth%NetBSD.org@localhost>
date:      Tue Aug 17 04:09:07 2010 +0000

description:
A few corrections:

- the return value from modcmd(MODULE_CMD_FINI) is not ignored;
  the module is only unloaded if the return value is 0
- if loading a module fails, the dependents won't be unloaded until
  the auto_unload timer goes off
- clarify that <module>.prop is merged with the dictionary passed
  in by modctl()
- clarify that other parts of the kernel shouldn't normally call
  module_unload()
- add some more source references and mention routines expected to
  be supplied by architecture dependent code

diffstat:

 share/man/man9/module.9 |  50 ++++++++++++++++++++++++++++++++++--------------
 1 files changed, 35 insertions(+), 15 deletions(-)

diffs (109 lines):

diff -r 368e57a0e917 -r 54d271e89a71 share/man/man9/module.9
--- a/share/man/man9/module.9   Tue Aug 17 01:45:51 2010 +0000
+++ b/share/man/man9/module.9   Tue Aug 17 04:09:07 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: module.9,v 1.14 2010/08/14 17:49:12 wiz Exp $
+.\"    $NetBSD: module.9,v 1.15 2010/08/17 04:09:07 jnemeth Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd August 11, 2010
+.Dd August 17, 2010
 .Dt MODULE 9
 .Os
 .Sh NAME
@@ -130,10 +130,6 @@
 and should return
 .Er ENOTTY
 if not implemented.
-The return values from
-.Fn modcmd
-are ignored for
-.Dv MODULE_CMD_FINI .
 .Pp
 For the
 .Dv MODULE_CMD_INIT
@@ -162,10 +158,11 @@
 If the specified module requires other modules, they are loaded first; if
 any required module cannot be loaded or if any of their
 .Fn modcmd
-control routines returns a non-zero status, loading of this module and all
-required modules will fail.
-Thus, the loading of a module and its required modules is an atomic
-operation.
+control routines returns a non-zero status, loading of this module and
+the specific required module will fail.
+The required modules are marked for automatic unloading.
+Thus, if the loading of the module failed, the required modules will
+be automatically unloaded after a short delay.
 .Pp
 The loader will look first for a built-in module with the specified
 .Fa name
@@ -202,9 +199,9 @@
 module file, but with the suffix
 .Dq Pa .prop .
 If this file is found, the prop_dictionary it contains is loaded and
-passed to the module's
-.Fn modcmd
-routine.
+merged with the prop_dictionary from the
+.Fa props
+argument.
 .Pp
 The
 .Fa class
@@ -278,8 +275,11 @@
 routine is called with a
 .Fa cmd
 argument of
-.Dv MODULE_CMD_FINI ,
-and the module is unloaded.
+.Dv MODULE_CMD_FINI .
+If the
+.Fn modcmd
+routine returns with an error, then the error is returned to the caller
+otherwise the module is unloaded.
 .Pp
 The reference counts of all modules that were required by this module are
 decremented, but the required modules are not unloaded by the call to
@@ -301,6 +301,7 @@
 .Xr modctl 2
 system call, by the module subsystem's internal auto-unload thread, or by
 other kernel facilities.
+Generally, other kernel facilities should not be calling this function.
 .It Fn module_init_class "class"
 Load and initialize all available modules of the specified
 .Fa class .
@@ -381,9 +382,28 @@
 and
 .Pa sys/kern/kern_module_vfs.c .
 .Pp
+The routines for linking the module are in
+.Pa sys/kern/subr_kobj.c .
+.Pp
+The routines for reading a module from the filesystem are in
+.Pa sys/kern/subr_kobj_vfs.c .
+.Pp
 The header file
 .In sys/sys/module.h
 describes the public interface.
+.Pp
+In addition, each architecture is expected to provide
+.Fn kobj_machdep ,
+.Fn kobj_reloc ,
+and
+.Fn module_init_md .
+.Fn kobj_machdep
+is for any machine dependent actions, such as flushing caches, that are
+needed when a module is loaded or unloaded.
+.Fn kobj_reloc
+deals with resolution of relocatable symbols.
+.Fn module_init_md
+is for finding modules passed in by the boot loader.
 .Sh SEE ALSO
 .Xr modctl 2
 .Sh HISTORY