Make a first pass at documenting the module(9) subsystem.
XXX This is by no means complete, but it is a beginning.
This commit is contained in:
parent
80ac55757e
commit
31f0dbbb9e
|
@ -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
|
||||
|
|
|
@ -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 \
|
||||
|
|
|
@ -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.
|
Loading…
Reference in New Issue