diff options
Diffstat (limited to 'static/netbsd/man9/module.9')
| -rw-r--r-- | static/netbsd/man9/module.9 | 617 |
1 files changed, 617 insertions, 0 deletions
diff --git a/static/netbsd/man9/module.9 b/static/netbsd/man9/module.9 new file mode 100644 index 00000000..3e44e6cc --- /dev/null +++ b/static/netbsd/man9/module.9 @@ -0,0 +1,617 @@ +.\" $NetBSD: module.9,v 1.55 2025/02/25 08:51:27 martin 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 July 21, 2021 +.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 , +.Nm module_find_section , +.Nm module_kernel , +.Nm module_name , +.Nm module_source , +.Nm module_register_callbacks , +.Nm module_unregister_callbacks , +.Nm module_specific_key_create , +.Nm module_specific_key_delete , +.Nm module_getspecific , +.Nm module_setspecific +.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 void +.Fn module_hold "module_t *module" +.Ft void +.Fn module_rele "module_t *module" +.Ft int +.Fn module_find_section "const char *" "void **" "size_t *" +.Ft "module_t *" +.Fn module_kernel "void" +.Ft "const char *" +.Fn module_name "struct module *module" +.Ft modsrc_t +.Fn module_source "struct module *module" +.Ft void +.Fn module_init "void" +.Ft void +.Fn module_start_unload_thread "void" +.Ft void +.Fn module_builtin_require_force "void" +.Ft void +.Fn module_load_vfs_init "void" +.Ft "void *" +.Fn module_register_callbacks "void (*)(struct module *)" \ +"void (*unload)(struct module *)" +.Ft void +.Fn module_unregister_callbacks "void *" +.Ft specificdata_key_t +.Fn module_specific_key_create "specificdata_key_t *keyp" \ +"specificdata_dtor_t dtor" +.Ft void +.Fn module_specific_key_delete "specificdata_key_t key" +.Ft "void *" +.Fn module_getspecific "module_t *mod" "specificdata_key_t key" +.Ft "void *" +.Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" +.Sh 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. +.Pp +The +.Nm +subsystem includes two data types: +.Bl -enum -offset indent +.It +The +.Vt module_t +type provides storage to describe a module. +.It +The +.Vt modinfo_t +type resides within +.Vt module_t +and contains module header info. +.El +.Pp +The module subsystem is protected by the global +.Va kernconfig_mutex . +.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 +.Fa class +argument identifies the class of module, and must be one of the following +(note that +.Dv MODULE_CLASS_ANY +should not be used here): +.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent +.It Dv MODULE_CLASS_VFS +The module provide a virtual file system - see +.Xr vfs 9 +.It Dv MODULE_CLASS_DRIVER +The module is a device driver - see +.Xr driver 9 +.It Dv MODULE_CLASS_EXEC +The module provides an alternate execution environment - see the various +.Dv COMPAT_xxx +options in +.Xr options 4 +.It Dv MODULE_CLASS_SECMODEL +The module provides a security model - see +.Xr secmodel 9 +.It Dv MODULE_CLASS_BUFQ +The module provides a buffer queue strategy - see +.Xr bufq 9 +.It Dv MODULE_CLASS_MISC +The module provides miscellaneous kernel services +.El +.Pp +The +.Fa name +argument provides the name of the module. +Loaded modules, including those that are built-in to the kernel, must all +have unique names. +.Pp +The +.Fa 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. +.Pp +If there are no required modules, this argument should be specified as +.Dv NULL . +.Pp +In addition to the explicit arguments, the +.Fn MODULE +macro creates a reference to the module's +.Fn modcmd +function. +This function is defined as: +.Bl -tag -width modcmd -offset indent +.It Ft int +.Fn xxx_modcmd "modcmd_t cmd" "void *data" +.El +.Pp +(where xxx is the name of the module, from the +.Dv MODULE +macro). +.Pp +The +.Fa cmd +argument requests one of the following operations: +.Bl -tag -width MODULE_CMD_AUTOUNLOAD -offset indent +.It Dv MODULE_CMD_INIT +Perform module-specific initialization when the module is loaded. +.It Dv MODULE_CMD_FINI +Perform module-specific clean-up before the module is unloaded. +.It Dv MODULE_CMD_AUTOUNLOAD +Notify the module that it is about to be unloaded. +.It Dv MODULE_CMD_STAT +Request the module to provide status information (not currently implemented). +.El +.Pp +All modules' +.Fn modcmd +functions must implement the +.Dv MODULE_CMD_INIT +and +.Dv MODULE_CMD_FINI +commands. +The other commands are optional, +and should return +.Er ENOTTY +if not implemented. +.Pp +For the +.Dv MODULE_CMD_INIT +command, the +.Fa data +argument is used to pass a pointer to the module's +.Xr prop_dictionary 3 . +For the +.Dv MODULE_CMD_STAT +command, the +.Fa data +argument points to a buffer where the status information should be placed. +.Pp +The __link_set mechanism is used to enable the +.Nm +subsystem to locate the +.Vt modinfo_t +structure. +.It Fn module_load "name" "flags" "props" "class" +Load a module, link it into the running kernel, and call the module's +.Fn modcmd +routine with a +.Fa cmd +argument of +.Dv 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 +.Fn 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. +.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, provided it has been mounted by the +initialization code. +.Pp +The +.Fa flags +argument can include: +.Bl -tag -width MODCTL_LOAD_FORCE -offset indent +.It Dv MODCTL_NO_PROP +When loading a module from the file system, do not attempt to locate a +corresponding prop_dictionary file. +.It Dv MODCTL_LOAD_FORCE +Force loading of disabled built-in modules and modules built for a +different version of the operating system. +.El +.Pp +The +.Fa props +argument points to an externalized property list which is passed to the +module's +.Fn modcmd +routine. +If a module is being loaded from the file system, and the +.Dv 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 +.Dq Pa .plist . +If this file is found, the prop_dictionary it contains is loaded and +merged with the prop_dictionary from the +.Fa props +argument. +.Pp +The +.Fa class +argument can be any of: +.Pp +.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent -compact +.It Dv MODULE_CLASS_ANY +.It Dv MODULE_CLASS_DRIVER +Device driver +.It Dv MODULE_CLASS_EXEC +Executable image handler +.It Dv MODULE_CLASS_MISC +Miscellaneous module +.It Dv MODULE_CLASS_SECMODEL +Security model (see +.Xr secmodel 9 +for more details) +.It Dv MODULE_CLASS_VFS +Virtual file system +.El +.Pp +If the class is not +.Dv MODULE_CLASS_ANY , +the class of the module being loaded +must match the requested +.Fa class . +Except when verifying a module's class when it is being loaded, module +classes other than +.Dv MODULE_CLASS_SECMODEL +are transparent to the module subsystem. +They are provided only for the benefit of the subsystem's clients. +Modules with class +.Dv MODULE_CLASS_SECMODEL +are automatically registered with +.Fn secmodel_register +after being successfully loaded, and automatically deregistered with +.Fn secmodel_deregister +when being unloaded. +.Pp +The +.Fn module_load +routine is primarily intended as the implementation of the +.Dv MODCTL_LOAD +option of the +.Xr modctl 2 +system call. +.It Fn module_autoload "name" "class" +Auto-load 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 module subsystem uses a kernel thread to attempt to automatically +unload modules a short time (currently, 10 seconds) after being loaded by +.Fn module_autoload . +Before the module is unloaded by this thread, its +.Fn modcmd +is called with the +.Fa cmd +argument specified as +.Dv MODULE_CMD_AUTOUNLOAD . +A module can prevent itself from being unloaded by returning a non-zero +value. +Exception: If +.Li kern.module.autounload_unsafe +is set, a module that returns +.Er ENOTTY , +meaning it does not understand the command, may still be autounloaded. +.Pp +The +.Fn 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. +.Pp +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 +.Dq Pa .plist . +If this file is found, the prop_dictionary it contains will be loaded and +passed to the module's +.Fn modcmd +routine. +If this prop_dictionary contains a +.Dq Pa noautoload +property which is set to +.Dq Pa true +then the system will refuse to load the module. +.It Fn module_unload "name" +Unload a module. +If the module's reference count is non-zero, the function returns +.Er EBUSY . +Otherwise, the module's +.Fn modcmd +routine is called with a +.Fa cmd +argument of +.Dv MODULE_CMD_FINI . +If the +.Fn modcmd +routine returns with an error, then the error is returned to the caller +otherwise the module is unloaded. +.Pp +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 +.Fn module_unload . +Instead, the required modules may be unloaded by subsequent calls to +.Fn module_unload . +.Pp +Unloading a built-in module causes the module to be marked as disabled. +This prevents the module from being re-loaded, except by the +.Fn module_load +function with the +.Fa flags +argument set to +.Dv MODULE_FORCE_LOAD . +.Pp +The +.Fn module_unload +function may be called by the +.Xr 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. +.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 "module" +Increment the reference count of a module. +A module cannot be unloaded if its reference count is non-zero. +.It Fn module_rele "module" +Decrement the reference count of a module. +.It Fn module_find_section "name" "addr" "size" +Find the start address and size of linker section +.Ar 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. +.It Fn module_kernel "void" +Returns a pointer to a +.Ft module_t +structure describing the kernel module. +.It Fn module_name module +Returns a pointer to the module's name. +.It Fn module_source module +Returns the source of the module, one of +.Dv MODULE_SOURCE_KERNEL , +.Dv MODULE_SOURCE_BOOT , +or +.Dv MODULE_SOURCE_FILESYS . +.It Fn module_init "void" +Initialize the module subsystem. +Creates and initializes various data structures, locates all built-in +modules, and establishes the sub-system's +.Xr sysctl 8 +tree. +.Fn module_init +is called early in system initialization to facilitate use of security model +modules. +.It Fn module_start_unload_thread "void" +Create the thread that attempts to automatically unload modules that were +loaded via the +.Fn module_autoload +routine. +The function is called only once, +after the scheduler and timer functions are initialized. +.It Fn 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 +.Dv MODCTL_LOAD_FORCE +is specified. +.Fn module_builtin_require_force +is called near the end of system initialization, after the +.Xr init 8 +process is created. +.It Fn module_load_vfs_init "void" +The module subsystem is initialized early, long before any file systems +are available. +After the root file system is mounted, +.Fn 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. +.It Fn module_register_callbacks "void (*load)(struct module *)" \ +"void (*unload)(struct module *)" +Register a new set of callbacks. +The +.Fa load +callback is invoked after any module (including this module) is +successfully loaded; the +.Fa unload +callback is invoked before any module is unloaded. +Each load or unload event can result in multiple invocations of the +callback routines. +An opaque cookie is returned which can be passed to +.Fn module_unregister_callbacks . +.It Fn module_unregister_callbacks "void *opaque" +Unregister a set of callback routines previously registered with +.Fn module_register_callbacks . +The +.Fa opaque +argument should be the return value from the previous +.Fn module_register_callbacks +call. +.It Fn module_specific_key_create "specificdata_key_t *keyp" \ +"specificdata_dtor_t dtor" +Creates a new specificdata_key for use within the +.Nm +domain. +The key identifier is returned in +.Fa keyp . +.It Fn module_specific_key_delete "specificdata_key_t key" +Deletes the specified specificdata_key +.Fa key +from the +.Nm +domain. +.It Fn module_getspecific "module_t *mod" "specificdata_key_t key" +Retrieves the value associated with +.Fa key +from module +.Fa mod . +.It Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" +Stores +.Fa data +as the value associated with +.Fa key +for module +.Fa mod . +.El +.Sh PROGRAMMING CONSIDERATIONS +The module subsystem is designed to be called recursively, but only within +a single LWP. +This permits one module's +.Fn modcmd +routine to load or unload other modules. +.Pp +Additional considerations: +.Bl -bullet -offset indent +.It +A module is not permitted to load or unload itself. +Attempts to load or unload a module from within its own +.Fn modcmd +routine will fail with +.Er EEXIST +or +.Er EBUSY , +respectively. +.It +Although a module can be loaded by using either +.Fn module_load +or +.Fn module_autoload , +it is not possible for the module's +.Fn 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 +.Dv MODULE_CMD_AUTOUNLOAD +command in its +.Fn modcmd +routine, or use +.Fn module_hold +to increment its reference count. +Note however that modules loaded manually with +.Xr modload 8 +are never auto-unloaded. +.El +.Sh EXAMPLES +A set of example modules is available in the +.Pa src/sys/modules/examples +directory hierarchy. +.Sh CODE REFERENCES +The core of the kernel module implementation is in +.Pa sys/kern/kern_module.c +and +.Pa sys/kern/kern_module_vfs.c . +.Pp +The routines for linking the module are in +.Pa sys/kern/subr_kobj.c . +.Pp +The routines for reading a module from the file system are in +.Pa sys/kern/subr_kobj_vfs.c . +.Pp +The header file +.In sys/sys/module.h +describes the public interface. +.Pp +In addition, each architecture is expected to provide +.Fn kobj_machdep , +.Fn kobj_reloc , +and +.Fn module_init_md . +.Fn kobj_machdep +is for any machine dependent actions, such as flushing caches, that are +needed when a module is loaded or unloaded. +.Fn kobj_reloc +deals with resolution of relocatable symbols. +.Fn module_init_md +is for finding modules passed in by the boot loader. +.Sh SEE ALSO +.Xr modctl 2 , +.Xr module 7 , +.Xr specificdata 9 , +.Xr intro 9lua +.Sh HISTORY +The kernel module subsystem first appeared in +.Nx 5.0 . +It replaces the +.Dq LKM +subsystem from earlier releases. +.Sh AUTHORS +.An -nosplit +The +.Nm +system was written by +.An Andrew Doran Aq Mt ad@NetBSD.org . +This manual page was written by +.An Paul Goyette Aq Mt pgoyette@NetBSD.org . |