NetBSD/share/man/man9/module.9

.\"	$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.