Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


MODULE(9)                  Kernel Developer's Manual                 MODULE(9)

NAME
     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 -
     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);

     void
     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);

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:

           1.   The module_t type provides storage to describe a module.

           2.   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 (note that MODULE_CLASS_ANY should not be used
           here):

                 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(4)

                 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:

                 modcmd_t
                         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 by this thread, 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.
           Exception: If kern.module.autounload_unsafe is set, a module that
           returns ENOTTY, meaning it does not understand the command, may
           still be autounloaded.

           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(module)
           Increment the reference count of a module.  A module cannot be
           unloaded if its reference count is non-zero.

     module_rele(module)
           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_kernel(void)
           Returns a pointer to a module_t structure describing the kernel
           module.

     module_name(module)
           Returns a pointer to the module's name.

     module_source(module)
           Returns the source of the module, one of MODULE_SOURCE_KERNEL,
           MODULE_SOURCE_BOOT, or MODULE_SOURCE_FILESYS.

     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(void)
           The module subsystem is initialized early, long before any file
           systems are available.  After the root file system is mounted,
           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 *))
           Register a new set of callbacks.  The load callback is invoked
           after any module (including this module) is successfully loaded;
           the 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 module_unregister_callbacks().

     module_unregister_callbacks(void *opaque)
           Unregister a set of callback routines previously registered with
           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)
           Creates a new specificdata_key for use within the module domain.
           The key identifier is returned in keyp.

     module_specific_key_delete(specificdata_key_t key)
           Deletes the specified specificdata_key key from the module domain.

     module_getspecific(module_t *mod, specificdata_key_t key)
           Retrieves the value associated with key from module mod.

     module_setspecific(module_t *mod, specificdata_key_t key, void *data)
           Stores data as the value associated with key for module mod.

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), specificdata(9), 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>.

NetBSD 10.99                     July 21, 2021                    NetBSD 10.99