diff --git a/distrib/sets/lists/comp/mi b/distrib/sets/lists/comp/mi index 4c8a53cb9b1b..003b1be43c33 100644 --- a/distrib/sets/lists/comp/mi +++ b/distrib/sets/lists/comp/mi @@ -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 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 3c0f3e9384d6..9a6f1f7745a4 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -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 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \ 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 @@ MLINKS+=microuptime.9 binuptime.9 \ 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 \ diff --git a/share/man/man9/module.9 b/share/man/man9/module.9 new file mode 100644 index 000000000000..855c75ac7cee --- /dev/null +++ b/share/man/man9/module.9 @@ -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.