Unix/Linux Go Back    


NetBSD 6.1.5 - man page for module (netbsd section 9)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

NAME
     module, module_load, module_autoload, module_unload, module_init_class, module_hold,
     module_rele, module_find_section -- 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(const char *name);

     void
     module_rele(const char *);

     int
     module_find_section(const char *, void **, size_t *);

     void
     module_init(void);

     void
     module_start_unload_thread(void);

     void
     module_builtin_require_force(void);

     void
     module_load_vfs_init(void);

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 hav-
     ing 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.

     Two data types are relevant for module:

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

	   2.	The modinfo_t type resides within the module itself, 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.  In addition to the
	   explicit arguments, the MODULE() macro creates a reference to the module's modcmd()
	   function.  This function is defined as:

		 int	 modcmd(modcmd_t cmd, void *data)

	   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 imple-
	   mented.

	   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 mod-
	   ules, 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 mod-
	   ule is still not found, an attempt is made to locate the module within the file sys-
	   tem, 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 mod-
	   ule'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_dic-
	   tionary it contains is loaded and merged with the prop_dictionary from the props argu-
	   ment.

	   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 subsys-
	   tem.  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 mod-
	   ules that have not been disabled, and any modules provided by the boot loader are
	   loaded.

     module_hold(name)
	   Increment the reference count of a module.  A module cannot be unloaded if its refer-
	   ence count is non-zero.

     module_rele(name)
	   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_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()
	   The module subsystem is initialized early, long before any file systems are available.
	   After the root file system is mounted, module_load_vfs_init() is used to enable load-
	   ing 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.

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:

	   o   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.

	   o   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 distin-
	       guish 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.

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 reso-
     lution of relocatable symbols.  module_init_md() is for finding modules passed in by the
     boot loader.

SEE ALSO
     modctl(2), module(7)

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>.

BSD					 October 18, 2011				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:20 PM.