MODULE(9)

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

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

# 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, 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`(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>.

April 8, 2019 | NetBSD 9.3