MODULE(9) | Kernel Developer's Manual | MODULE(9) |
module
, module_load
,
module_autoload
,
module_unload
,
module_init_class
,
module_hold
, module_rele
,
module_find_section
,
module_kernel
, module_name
,
module_source
,
module_register_callbacks
,
module_unregister_callbacks
,
module_specific_key_create
,
module_specific_key_delete
,
module_getspecific
,
module_setspecific
—
#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
(module_t
*module);
void
module_rele
(module_t
*module);
int
module_find_section
(const
char *, void **,
size_t *);
module_t *
module_kernel
(void);
const char *
module_name
(struct
module *module);
modsrc_t
module_source
(struct
module *module);
void
module_init
(void);
void
module_start_unload_thread
(void);
void
module_builtin_require_force
(void);
void
module_load_vfs_init
(void);
void *
module_register_callbacks
(void
(*)(struct module *),
void (*unload)(struct module
*));
void
module_unregister_callbacks
(void
*);
specificdata_key_t
module_specific_key_create
(specificdata_key_t
*keyp,
specificdata_dtor_t
dtor);
void
module_specific_key_delete
(specificdata_key_t
key);
void *
module_getspecific
(module_t
*mod, specificdata_key_t
key);
void *
module_setspecific
(module_t
*mod, specificdata_key_t
key, void
*data);
The module
subsystem includes two data
types:
The module subsystem is protected by the global kernconfig_mutex.
MODULE
(class,
name, required)MODULE
() macro creates and initializes a
modinfo_t structure. The class
argument identifies the class of module, and must be one of the following
(note that MODULE_CLASS_ANY
should not be used
here):
MODULE_CLASS_VFS
MODULE_CLASS_DRIVER
MODULE_CLASS_EXEC
COMPAT_xxx
options in
options(4)MODULE_CLASS_SECMODEL
MODULE_CLASS_BUFQ
MODULE_CLASS_MISC
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:
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
MODULE_CMD_FINI
MODULE_CMD_AUTOUNLOAD
MODULE_CMD_STAT
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)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
MODCTL_LOAD_FORCE
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
MODULE_CLASS_EXEC
MODULE_CLASS_MISC
MODULE_CLASS_SECMODEL
MODULE_CLASS_VFS
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)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)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)module_hold
(module)module_rele
(module)module_find_section
(name,
addr, size)module_kernel
(void)module_name
(module)module_source
(module)MODULE_SOURCE_KERNEL
,
MODULE_SOURCE_BOOT
, or
MODULE_SOURCE_FILESYS
.module_init
(void)module_init
() is called early in system
initialization to facilitate use of security model modules.module_start_unload_thread
(void)module_autoload
() routine. The
function is called only once, after the scheduler and timer functions are
initialized.module_builtin_require_force
(void)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
(void)module_load_vfs_init
(void)
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.module_register_callbacks
(void
(*load)(struct module *), void (*unload)(struct module
*))module_unregister_callbacks
().module_unregister_callbacks
(void
*opaque)module_register_callbacks
(). The
opaque argument should be the return value from the
previous module_register_callbacks
() call.module_specific_key_create
(specificdata_key_t
*keyp, specificdata_dtor_t dtor)module
domain. The key identifier is returned in
keyp.module_specific_key_delete
(specificdata_key_t
key)module
domain.module_getspecific
(module_t
*mod, specificdata_key_t key)module_setspecific
(module_t
*mod, specificdata_key_t key,
void *data)modcmd
() routine
to load or unload other modules.
Additional considerations:
modcmd
()
routine will fail with EEXIST
or
EBUSY
, respectively.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.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.
module
system was written by Andrew
Doran
<ad@NetBSD.org>. This
manual page was written by Paul Goyette
<pgoyette@NetBSD.org>.
April 8, 2019 | NetBSD 9.0 |