| 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);
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);
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_VFSMODULE_CLASS_DRIVERMODULE_CLASS_EXECCOMPAT_xxx options in
          options(4)MODULE_CLASS_SECMODELMODULE_CLASS_BUFQMODULE_CLASS_MISCThe 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_INITMODULE_CMD_FINIMODULE_CMD_AUTOUNLOADMODULE_CMD_STATAll 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_PROPMODCTL_LOAD_FORCEThe 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_ANYMODULE_CLASS_DRIVERMODULE_CLASS_EXECMODULE_CLASS_MISCMODULE_CLASS_SECMODELMODULE_CLASS_VFSIf 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 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)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>.
| July 21, 2021 | NetBSD 10.0 |