module_init man page on NetBSD

Man page or keyword search:  
man Server   9087 pages
apropos Keyword Search (all sections)
Output format
NetBSD logo
[printable version]

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 selec‐
     tively 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.

     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 con‐
		tains 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 imple‐
					mented).

	   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 mod‐
	   ule'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 sys‐
				    tem, do not attempt to locate a corre‐
				    sponding 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 mod‐
	   ule file, but with the suffix “.plist”.  If this file is found, the
	   prop_dictionary it contains is loaded and merged with the prop_dic‐
	   tionary 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 regis‐
	   tered 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 implementa‐
	   tion 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 automati‐
	   cally 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 compo‐
	   nents 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 mod‐
	   ule 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 dis‐
	   abled.  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(name)
	   Increment the reference count of a module.  A module cannot be
	   unloaded if its reference 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 ini‐
	   tialized;  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 sys‐
	   tem 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 success‐
	   fully 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 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.

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 refer‐
	       ence 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 resolution 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 man‐
     ual page was written by Paul Goyette ⟨pgoyette@NetBSD.org⟩.

BSD			       October 18, 2011				   BSD
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server NetBSD

List of man pages available for NetBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net