Module Name: src
Committed By: pgoyette
Date: Sat Jul 31 03:14:07 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: module.9
Log Message:
Make a first pass at documenting the module(9) subsystem.
XXX This is by no means complete, but it is a beginning.
To generate a diff of this commit:
cvs rdiff -u -r1.1487 -r1.1488 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.337 -r1.338 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/module.9
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/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1487 src/distrib/sets/lists/comp/mi:1.1488
--- src/distrib/sets/lists/comp/mi:1.1487 Fri Jul 30 09:12:58 2010
+++ src/distrib/sets/lists/comp/mi Sat Jul 31 03:14:06 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1487 2010/07/30 09:12:58 jruoho Exp $
+# $NetBSD: mi,v 1.1488 2010/07/31 03:14:06 pgoyette Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -9350,6 +9350,13 @@
./usr/share/man/cat9/mi_switch.0 comp-sys-catman .cat
./usr/share/man/cat9/microtime.0 comp-sys-catman .cat
./usr/share/man/cat9/microuptime.0 comp-sys-catman .cat
+./usr/share/man/cat9/module.0 comp-sys-catman .cat
+./usr/share/man/cat9/module_autoload.0 comp-sys-catman .cat
+./usr/share/man/cat9/module_hold.0 comp-sys-catman .cat
+./usr/share/man/cat9/module_init_class.0 comp-sys-catman .cat
+./usr/share/man/cat9/module_load.0 comp-sys-catman .cat
+./usr/share/man/cat9/module_rele.0 comp-sys-catman .cat
+./usr/share/man/cat9/module_unload.0 comp-sys-catman .cat
./usr/share/man/cat9/mono_time.0 comp-obsolete obsolete
./usr/share/man/cat9/mstohz.0 comp-sys-catman .cat
./usr/share/man/cat9/mtocl.0 comp-sys-catman .cat
@@ -15122,6 +15129,13 @@
./usr/share/man/html9/mi_switch.html comp-sys-htmlman html
./usr/share/man/html9/microtime.html comp-sys-htmlman html
./usr/share/man/html9/microuptime.html comp-sys-htmlman html
+./usr/share/man/html9/module.html comp-sys-htmlman html
+./usr/share/man/html9/module_autoload.html comp-sys-htmlman html
+./usr/share/man/html9/module_hold.html comp-sys-htmlman html
+./usr/share/man/html9/module_init_class.html comp-sys-htmlman html
+./usr/share/man/html9/module_load.html comp-sys-htmlman html
+./usr/share/man/html9/module_rele.html comp-sys-htmlman html
+./usr/share/man/html9/module_unload.html comp-sys-htmlman html
./usr/share/man/html9/mstohz.html comp-sys-htmlman html
./usr/share/man/html9/mtocl.html comp-sys-htmlman html
./usr/share/man/html9/mtod.html comp-sys-htmlman html
@@ -21055,6 +21069,13 @@
./usr/share/man/man9/mi_switch.9 comp-sys-man .man
./usr/share/man/man9/microtime.9 comp-sys-man .man
./usr/share/man/man9/microuptime.9 comp-sys-man .man
+./usr/share/man/man9/module.9 comp-sys-man .man
+./usr/share/man/man9/module_autoload.9 comp-sys-man .man
+./usr/share/man/man9/module_hold.9 comp-sys-man .man
+./usr/share/man/man9/module_init_class.9 comp-sys-man .man
+./usr/share/man/man9/module_load.9 comp-sys-man .man
+./usr/share/man/man9/module_rele.9 comp-sys-man .man
+./usr/share/man/man9/module_unload.9 comp-sys-man .man
./usr/share/man/man9/mono_time.9 comp-obsolete obsolete
./usr/share/man/man9/mstohz.9 comp-sys-man .man
./usr/share/man/man9/mtocl.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.337 src/share/man/man9/Makefile:1.338
--- src/share/man/man9/Makefile:1.337 Fri Jul 30 09:13:00 2010
+++ src/share/man/man9/Makefile Sat Jul 31 03:14:05 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.337 2010/07/30 09:13:00 jruoho Exp $
+# $NetBSD: Makefile,v 1.338 2010/07/31 03:14:05 pgoyette Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -34,7 +34,7 @@
makeiplcookie.9 \
malloc.9 mb.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memoryallocators.9 \
memmove.9 memset.9 \
- microtime.9 microuptime.9 mi_switch.9 \
+ microtime.9 microuptime.9 mi_switch.9 module.9 \
mstohz.9 mutex.9 m_tag.9 namecache.9 \
namei.9 nullop.9 opencrypto.9 optstr.9 \
panic.9 pci.9 pci_configure_bus.9 pci_intr.9 pckbport.9 \
@@ -434,6 +434,12 @@
microuptime.9 getmicrouptime.9 \
microuptime.9 nanouptime.9 \
microuptime.9 getnanouptime.9
+MLINKS+=module.9 module_autoload.9 \
+ module.9 module_hold.9 \
+ module.9 module_init_class.9 \
+ module.9 module_load.9 \
+ module.9 module_rele.9 \
+ module.9 module_unload.9
MLINKS+=mstohz.9 hztoms.9
MLINKS+=mutex.9 mutex_init.9 mutex.9 mutex_destroy.9 mutex.9 mutex_enter.9 \
mutex.9 mutex_exit.9 mutex.9 mutex_tryenter.9 mutex.9 mutex_owned.9 \
Added files:
Index: src/share/man/man9/module.9
diff -u /dev/null src/share/man/man9/module.9:1.1
--- /dev/null Sat Jul 31 03:14:07 2010
+++ src/share/man/man9/module.9 Sat Jul 31 03:14:05 2010
@@ -0,0 +1,226 @@
+.\" $NetBSD: module.9,v 1.1 2010/07/31 03:14:05 pgoyette Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Andrew Doran.
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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.
+.\"
+.Dd August 1, 2010
+.Dt MODULE 9
+.Os
+.Sh NAME
+.Nm module ,
+.Nm module_load ,
+.Nm module_autoload ,
+.Nm module_unload ,
+.Nm module_init_class ,
+.Nm module_hold ,
+.Nm module_rele
+.Nd kernel module loader
+.Sh SYNOPSIS
+.In sys/module.h
+.Fn MODULE "class" "name" "required"
+.Ft int
+.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" "modclass_t class"
+.Ft int
+.Fn module_autoload "const char *name" "modclass_t class"
+.Ft int
+.Fn module_unload "const char *name"
+.Ft void
+.Fn module_init_class "modclass_t class"
+.Ft int
+.Fn module_hold "const char *name"
+.Ft void
+.Fn module_rele "const char *"
+.Sh DESCRIPTION
+Modules are sections of code that can be independantly linked and selectively
+loaded into or unloaded from a running kernel.
+This provides a mechanism to update the module without having to relink
+the kernel and reboot.
+Modules can be loaded from with the kernel image, provided by the boot
+loader, or loaded from the file system.
+.Pp
+The
+.Vt module_t
+type provides storage to describe a module.
+.Pp
+The
+.Vt modinfo_t
+type contains module header info.
+.Sh FUNCTIONS
+.Bl -tag -width abcd
+.It Fn MODULE "class" "name" "required"
+The
+.Fn MODULE
+macro creates and initializes a
+.Vt modinfo_t
+structure.
+The __link_set mechanism is used to enable the
+.Nm
+subsystem to local the structure.
+.It Fn module_load "name" "flags" "props" "class"
+.Pp
+Loads a module, links it into the running kernel, and calls the module's
+.Fn modcmd
+routine with an argument of MODULE_CMD_INIT.
+If the specified module requires other modules, they are loaded first; if
+any required modules cannot be loaded or their
+.Fn modcmd
+control routines returns a non-zero status, loading of this module will fail.
+.Pp
+The loader will look first for a built-in module with the specified
+.Fa name
+that has not been disabled (see
+.Fn module_unload
+below).
+If a built-in module with that
+.Fa name
+is not found, the list of modules prepared by the boot loader is searched.
+If the named module is still not found, an attempt is made to locate the
+module within the file system.
+.Pp
+The
+.Fa flags
+argument can include
+.Bl -tag -width abcd
+.It MODCTL_NO_PROP
+.It MODCTL_LOAD_FORCE force loading of disabled built-in modules
+.El
+.Pp
+The
+.Fa props
+argument points to an externalized property list which is passed to the
+module's
+.Fn modcmd
+routine.
+.Pp
+The
+.Fa class
+argument can be any of MODULE_CLASS_ANY, MODULE_CLASS_MISC, MODULE_CLASS_VFS,
+MODULE_CLASS_DRIVER, MODULE_CLASS_EXEC, or MODULE_CLASS_SECMODEL.
+If the class is not MODULE_CLASS_ANY, the class of the module being loaded
+must match the requested class.
+.Pp
+The
+.Fn module_load
+routine is primarily intended as the implementation of the MODCTL_LOAD
+option of the
+.Xr modctl 2
+system call.
+.It Fn module_autoload "name" "class"
+Auto-loads a module, making it available for automatic unloading.
+The
+.Fa name
+and
+.Fa class
+arguments are the same as for the
+.Fn module_load
+routine.
+.Pp
+The system may attempt to may unloaded modules that were loaded by
+.Fn module_autoload
+after a short period of time (currently, 10 seconds).
+Before the module is unloaded, its
+.Fn modcmd
+is called with MODULE_CMD_AUTOUNLOAD.
+A module can prevent itself from being unloaded by returning a non-zero
+value.
+.Pp
+.Fn module_autoload
+is intended for use by kernel components to locate and load optional
+system components.
+.Fn module_autoload
+is also used to load modules that are required by other modules.
+.It Fn module_unload "name"
+.Pp
+Unload a module.
+If the module's reference count is non-zero, returns EBUSY.
+Otherwise, the module's
+.Fn modcmd
+routine is called with MODULE_CMD_FINI, and the module is unloaded.
+The reference counts of all modules that were required by this module are
+decremented, however the required modules are not unloaded by this call to
+.Fn module_unload .
+(They may be unloaded by subsequent calls to
+.Fn module_unload .)
+.Pp
+Unloading a built-in module causes that module to be marked disabled.
+This prevents the module from being re-loaded, except by the
+.Fn module_load
+function with the
+.Fa flags
+argument set to MODULE_FORCE_LOAD.
+.Pp
+.Fn module_unload
+may be called by the
+.Xr modctl 2
+system call, by the module subsystem's internal auto-unload thread, or by
+other kernel facilities.
+.It Fn module_init_class "class"
+Load and initialize all available modules of the specified
+.Fa class .
+Any built-in modules that have not been disabled, and any modules provided
+by the boot loader are loaded.
+.It Fn module_hold "name"
+Increment the reference count of a module.
+A module cannot be unload if its reference count is non-zero.
+.It Fn module_rele "name"
+Decrement the reference count of a module.
+.Pp
+.El
+.Sh LOCK PROTOCOL
+The
+.Nm
+subsystem is protected with the global
+.Vt module_mutex .
+This mutex must be acquired before calling any of these routines.
+(As an exception, the
+.Fn module_load
+routine acquires the mutex itself, so one does not need to acquire it
+before calling
+.Fn module_load .)
+Loading of a module and its required modules occurs as an atomic
+operation, and either completely succeeds or completely fails.
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where code implementing the kernel module loader can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The core of the kernel module implementation is in
+.Pa sys/kern/kern_module.c
+and
+.Pa sys/kern/kerm_module_vfs.c .
+.Pp
+The header file
+.Pa sys/sys/module.h
+describes the public interface.
+.Sh SEE ALSO
+.Xr modctl 2
+.Sh HISTORY
+The kernel module subsystem first appeared in
+.Nx 5.0 .
+It replaces the lkm subsystem from earlier releases.
