NAME
module,
module_load,
module_autoload,
module_unload,
module_init_class,
module_hold,
module_rele,
module_find_section —
kernel module loader
SYNOPSIS
#include <sys/module.h>
MODULE(
class,
name,
required);
int
module_load(
const
char *name,
int
flags,
prop_dictionary_t
props,
modclass_t
class);
int
module_autoload(
const
char *name,
modclass_t
class);
int
module_unload(
const
char *name);
void
module_init_class(
modclass_t
class);
int
module_hold(
const
char *name);
void
module_rele(
const
char *);
int
module_find_section(
const
char *,
void **,
size_t *);
void
module_init(
void);
void
module_start_unload_thread(
void);
void
module_builtin_require_force(
void);
void
module_load_vfs_init(
void);
DESCRIPTION
Modules are sections of code that can be independently 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 within the kernel image, provided by the boot loader, or loaded
from the file system.
The
module subsystem includes two data types:
- The module_t type provides storage
to describe a module.
- The modinfo_t type resides within
module_t and contains module header info.
The module subsystem is protected by the global
kernconfig_mutex.
FUNCTIONS
-
-
- MODULE(class,
name, required)
- The MODULE() macro creates and
initializes a modinfo_t structure. The
class argument identifies the class of module, and
must be one of the following:
-
-
MODULE_CLASS_VFS
- The module provide a virtual file system - see
vfs(9)
-
-
MODULE_CLASS_DRIVER
- The module is a device driver - see
driver(9)
-
-
MODULE_CLASS_EXEC
- The module provides an alternate execution environment
- see the various
COMPAT_xxx
options in
options(9)
-
-
MODULE_CLASS_SECMODEL
- The module provides a security model - see
secmodel(9)
-
-
MODULE_CLASS_BUFQ
- The module provides a buffer queue strategy - see
bufq(9)
-
-
MODULE_CLASS_MISC
- The module provides miscellaneous kernel services
The name argument provides the name of the module.
Loaded modules, including those that are built-in to the kernel, must all
have unique names.
The required argument is a quoted string containing a
comma-separated list of module names that are required by this module. The
list must not contain any white-space. When a module is loaded, all of its
required modules are auto-loaded and initialized before the module itself
is loaded. Loading of required modules is a recursive operation.
If there are no required modules, this argument should be specified as
NULL
.
In addition to the explicit arguments, the MODULE() macro
creates a reference to the module's modcmd() function.
This function is defined as:
-
-
- int
- xxx_modcmd(modcmd_t
cmd, void *data)
(where xxx is the name of the module, from the
MODULE
macro).
The cmd argument requests one of the following
operations:
-
-
MODULE_CMD_INIT
- Perform module-specific initialization when the module
is loaded.
-
-
MODULE_CMD_FINI
- Perform module-specific clean-up before the module is
unloaded.
-
-
MODULE_CMD_AUTOUNLOAD
- Notify the module that it is about to be unloaded.
-
-
MODULE_CMD_STAT
- Request the module to provide status information (not
currently implemented).
All modules' modcmd() functions must implement the
MODULE_CMD_INIT
and
MODULE_CMD_FINI
commands. The other commands are
optional, and should return ENOTTY
if not
implemented.
For the MODULE_CMD_INIT
command, the
data argument is used to pass a pointer to the
module's
prop_dictionary(3).
For the MODULE_CMD_STAT
command, the
data argument points to a buffer where the status
information should be placed.
The __link_set mechanism is used to enable the module
subsystem to locate the modinfo_t structure.
-
-
- module_load(name,
flags, props,
class)
- Load a module, link it into the running kernel, and call
the module's modcmd() routine with a
cmd argument of
MODULE_CMD_INIT
. If the specified module requires
other modules, they are loaded first; if any required module cannot be
loaded or if any of their modcmd() 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.
The loader will look first for a built-in module with the specified
name that has not been disabled (see
module_unload() below). If a built-in module with that
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, provided it
has been mounted by the initialization code.
The flags argument can include:
-
-
MODCTL_NO_PROP
- When loading a module from the file system, do not
attempt to locate a corresponding prop_dictionary file.
-
-
MODCTL_LOAD_FORCE
- Force loading of disabled built-in modules and modules
built for a different version of the operating system.
The props argument points to an externalized property
list which is passed to the module's modcmd() routine.
If a module is being loaded from the file system, and the
MODCTL_NO_PROP
flag is not set, the system
searches for a file with the same name as the module file, but with the
suffix “.plist”. If this file is found, the
prop_dictionary it contains is loaded and merged with the prop_dictionary
from the props argument.
The class argument can be any of:
MODULE_CLASS_ANY
-
MODULE_CLASS_DRIVER
- Device driver
MODULE_CLASS_EXEC
- Executable image handler
MODULE_CLASS_MISC
- Miscellaneous module
MODULE_CLASS_SECMODEL
- Security model (see
secmodel(9) for more
details)
MODULE_CLASS_VFS
- Virtual file system
If the class is not MODULE_CLASS_ANY
, the class of
the module being loaded must match the requested
class. Except when verifying a module's class when
it is being loaded, module classes other than
MODULE_CLASS_SECMODEL
are transparent to the
module subsystem. They are provided only for the benefit of the
subsystem's clients. Modules with class
MODULE_CLASS_SECMODEL
are automatically registered
with secmodel_register() after being successfully
loaded, and automatically deregistered with
secmodel_deregister() when being unloaded.
The module_load() routine is primarily intended as the
implementation of the MODCTL_LOAD
option of the
modctl(2) system call.
-
-
- module_autoload(name,
class)
- Auto-load a module, making it available for automatic
unloading. The name and class
arguments are the same as for the module_load() routine.
The module subsystem uses a kernel thread to attempt to automatically unload
modules a short time (currently, 10 seconds) after being loaded by
module_autoload(). Before the module is unloaded, its
modcmd() is called with the cmd
argument specified as
MODULE_CMD_AUTOUNLOAD
. A
module can prevent itself from being unloaded by returning a non-zero
value.
The module_autoload() function is intended for use by
kernel components to locate and load optional system components. The
function is also used to load modules that are required by other modules.
The directory from which the module is loaded will be searched for a file
with the same name as the module file, but with the suffix
“.plist”. If this file is found, the
prop_dictionary it contains will be loaded and passed to the module's
modcmd() routine. If this prop_dictionary contains a
“noautoload” property which is set to
“true” then the system will refuse to load
the module.
-
-
- module_unload(name)
- Unload a module. If the module's reference count is
non-zero, the function returns
EBUSY
. Otherwise,
the module's modcmd() routine is called with a
cmd argument of
MODULE_CMD_FINI
. If the modcmd()
routine returns with an error, then the error is returned to the caller
otherwise the module is unloaded.
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
module_unload(). Instead, the required modules may be
unloaded by subsequent calls to module_unload().
Unloading a built-in module causes the module to be marked as disabled. This
prevents the module from being re-loaded, except by the
module_load() function with the
flags argument set to
MODULE_FORCE_LOAD
.
The module_unload() function may be called by the
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.
-
-
- module_init_class(class)
- Load and initialize all available modules of the specified
class. Any built-in modules that have not been
disabled, and any modules provided by the boot loader are loaded.
-
-
- module_hold(name)
- Increment the reference count of a module. A module cannot
be unloaded if its reference count is non-zero.
-
-
- module_rele(name)
- Decrement the reference count of a module.
-
-
- module_find_section(name,
addr, size)
- Find the start address and size of linker section
name within a module. The miniroot module uses this
routine to find the address and size of the embedded file system image.
This routine can only examine the linker data for the module that is
currently being initialized; it cannot examine data for any other
module.
-
-
- module_init(void)
- Initialize the module subsystem. Creates and initializes
various data structures, locates all built-in modules, and establishes the
sub-system's sysctl(8) tree.
module_init() is called early in system initialization
to facilitate use of security model modules.
-
-
- module_start_unload_thread(void)
- Create the thread that attempts to automatically unload
modules that were loaded via the module_autoload()
routine. The function is called only once, after the scheduler and timer
functions are initialized.
-
-
- module_builtin_require_force(void)
- Mark as "disabled" any built-in modules that have
not been successfully initialized. Modules marked "disabled" can
only be loaded if the
MODCTL_LOAD_FORCE
is
specified. module_builtin_require_force() is called near
the end of system initialization, after the
init(8) process is
created.
-
-
- module_load_vfs_init()
- The module subsystem is initialized early, long before any
file systems are available. After the root file system is mounted,
module_load_vfs_init() is used to enable loading modules
from the file system. Until this routine is called, modules can only be
loaded if they were built-in to the kernel image or provided by the boot
loader.
PROGRAMMING CONSIDERATIONS
The module subsystem is designed to be called recursively, but only within a
single LWP. This permits one module's
modcmd() routine to
load or unload other modules.
Additional considerations:
- A module is not permitted to load or unload itself.
Attempts to load or unload a module from within its own
modcmd() routine will fail with
EEXIST
or EBUSY
,
respectively.
- Although a module can be loaded by using either
module_load() or module_autoload(), it
is not possible for the module's modcmd() routine to
distinguish between the two methods. Any module which needs to ensure that
it does not get auto-unloaded must either handle the
MODULE_CMD_AUTOUNLOAD
command in its
modcmd() routine, or use module_hold()
to increment its reference count. Note however that modules loaded
manually with modload(8)
are never auto-unloaded.
EXAMPLES
A set of example modules is available in the
src/sys/modules/examples directory hierarchy.
CODE REFERENCES
The core of the kernel module implementation is in
sys/kern/kern_module.c and
sys/kern/kern_module_vfs.c.
The routines for linking the module are in
sys/kern/subr_kobj.c.
The routines for reading a module from the file system are in
sys/kern/subr_kobj_vfs.c.
The header file
<sys/sys/module.h>
describes the public interface.
In addition, each architecture is expected to provide
kobj_machdep(),
kobj_reloc(), and
module_init_md().
kobj_machdep() is for
any machine dependent actions, such as flushing caches, that are needed when a
module is loaded or unloaded.
kobj_reloc() deals with
resolution of relocatable symbols.
module_init_md() is for
finding modules passed in by the boot loader.
SEE ALSO
modctl(2),
module(7),
intro(9lua)
HISTORY
The kernel module subsystem first appeared in
NetBSD
5.0. It replaces the “LKM” subsystem from earlier releases.
AUTHORS
The
module system was written by
Andrew
Doran
<
ad@NetBSD.org>. This
manual page was written by
Paul Goyette
<
pgoyette@NetBSD.org>.