1.\" $NetBSD: module.9,v 1.42 2017/12/20 10:01:38 wiz Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 16, 2017 31.Dt MODULE 9 32.Os 33.Sh NAME 34.Nm module , 35.Nm module_load , 36.Nm module_autoload , 37.Nm module_unload , 38.Nm module_init_class , 39.Nm module_hold , 40.Nm module_rele , 41.Nm module_find_section 42.Nd kernel module loader 43.Sh SYNOPSIS 44.In sys/module.h 45.Fn MODULE "class" "name" "required" 46.Ft int 47.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \ 48"modclass_t class" 49.Ft int 50.Fn module_autoload "const char *name" "modclass_t class" 51.Ft int 52.Fn module_unload "const char *name" 53.Ft void 54.Fn module_init_class "modclass_t class" 55.Ft int 56.Fn module_hold "const char *name" 57.Ft void 58.Fn module_rele "const char *" 59.Ft int 60.Fn module_find_section "const char *" "void **" "size_t *" 61.Ft void 62.Fn module_init "void" 63.Ft void 64.Fn module_start_unload_thread "void" 65.Ft void 66.Fn module_builtin_require_force "void" 67.Ft void 68.Fn module_load_vfs_init "void" 69.Sh DESCRIPTION 70Modules are sections of code that can be independently linked and selectively 71loaded into or unloaded from a running kernel. 72This provides a mechanism to update the module without having to relink 73the kernel and reboot. 74Modules can be loaded from within the kernel image, provided by the boot 75loader, or loaded from the file system. 76.Pp 77The 78.Nm 79subsystem includes two data types: 80.Bl -enum -offset indent 81.It 82The 83.Vt module_t 84type provides storage to describe a module. 85.It 86The 87.Vt modinfo_t 88type resides within 89.Vt module_t 90and contains module header info. 91.El 92.Pp 93The module subsystem is protected by the global 94.Va kernconfig_mutex . 95.Sh FUNCTIONS 96.Bl -tag -width abcd 97.It Fn MODULE "class" "name" "required" 98The 99.Fn MODULE 100macro creates and initializes a 101.Vt modinfo_t 102structure. 103The 104.Fa class 105argument identifies the class of module, and must be one of the following: 106.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent 107.It Dv MODULE_CLASS_VFS 108The module provide a virtual file system - see 109.Xr vfs 9 110.It Dv MODULE_CLASS_DRIVER 111The module is a device driver - see 112.Xr driver 9 113.It Dv MODULE_CLASS_EXEC 114The module provides an alternate execution environment - see the various 115.Dv COMPAT_xxx 116options in 117.Xr options 4 118.It Dv MODULE_CLASS_SECMODEL 119The module provides a security model - see 120.Xr secmodel 9 121.It Dv MODULE_CLASS_BUFQ 122The module provides a buffer queue strategy - see 123.Xr bufq 9 124.It Dv MODULE_CLASS_MISC 125The module provides miscellaneous kernel services 126.El 127.Pp 128The 129.Fa name 130argument provides the name of the module. 131Loaded modules, including those that are built-in to the kernel, must all 132have unique names. 133.Pp 134The 135.Fa required 136argument is a quoted string containing a comma-separated list of module 137names that are required by this module. 138The list must not contain any white-space. 139When a module is loaded, all of its required modules are auto-loaded and 140initialized before the module itself is loaded. 141Loading of required modules is a recursive operation. 142.Pp 143If there are no required modules, this argument should be specified as 144.Dv NULL . 145.Pp 146In addition to the explicit arguments, the 147.Fn MODULE 148macro creates a reference to the module's 149.Fn modcmd 150function. 151This function is defined as: 152.Bl -tag -width modcmd -offset indent 153.It Ft int 154.Fn xxx_modcmd "modcmd_t cmd" "void *data" 155.El 156.Pp 157(where xxx is the name of the module, from the 158.Dv MODULE 159macro). 160.Pp 161The 162.Fa cmd 163argument requests one of the following operations: 164.Bl -tag -width MODULE_CMD_AUTOUNLOAD -offset indent 165.It Dv MODULE_CMD_INIT 166Perform module-specific initialization when the module is loaded. 167.It Dv MODULE_CMD_FINI 168Perform module-specific clean-up before the module is unloaded. 169.It Dv MODULE_CMD_AUTOUNLOAD 170Notify the module that it is about to be unloaded. 171.It Dv MODULE_CMD_STAT 172Request the module to provide status information (not currently implemented). 173.El 174.Pp 175All modules' 176.Fn modcmd 177functions must implement the 178.Dv MODULE_CMD_INIT 179and 180.Dv MODULE_CMD_FINI 181commands. 182The other commands are optional, 183and should return 184.Er ENOTTY 185if not implemented. 186.Pp 187For the 188.Dv MODULE_CMD_INIT 189command, the 190.Fa data 191argument is used to pass a pointer to the module's 192.Xr prop_dictionary 3 . 193For the 194.Dv MODULE_CMD_STAT 195command, the 196.Fa data 197argument points to a buffer where the status information should be placed. 198.Pp 199The __link_set mechanism is used to enable the 200.Nm 201subsystem to locate the 202.Vt modinfo_t 203structure. 204.It Fn module_load "name" "flags" "props" "class" 205Load a module, link it into the running kernel, and call the module's 206.Fn modcmd 207routine with a 208.Fa cmd 209argument of 210.Dv MODULE_CMD_INIT . 211If the specified module requires other modules, they are loaded first; if 212any required module cannot be loaded or if any of their 213.Fn modcmd 214control routines returns a non-zero status, loading of this module and 215the specific required module will fail. 216The required modules are marked for automatic unloading. 217Thus, if the loading of the module failed, the required modules will 218be automatically unloaded after a short delay. 219.Pp 220The loader will look first for a built-in module with the specified 221.Fa name 222that has not been disabled (see 223.Fn module_unload 224below). 225If a built-in module with that 226.Fa name 227is not found, the list of modules prepared by the boot loader is searched. 228If the named module is still not found, an attempt is made to locate the 229module within the file system, provided it has been mounted by the 230initialization code. 231.Pp 232The 233.Fa flags 234argument can include: 235.Bl -tag -width MODCTL_LOAD_FORCE -offset indent 236.It Dv MODCTL_NO_PROP 237When loading a module from the file system, do not attempt to locate a 238corresponding prop_dictionary file. 239.It Dv MODCTL_LOAD_FORCE 240Force loading of disabled built-in modules and modules built for a 241different version of the operating system. 242.El 243.Pp 244The 245.Fa props 246argument points to an externalized property list which is passed to the 247module's 248.Fn modcmd 249routine. 250If a module is being loaded from the file system, and the 251.Dv MODCTL_NO_PROP 252flag is not set, the system searches for a file with the same name as the 253module file, but with the suffix 254.Dq Pa .plist . 255If this file is found, the prop_dictionary it contains is loaded and 256merged with the prop_dictionary from the 257.Fa props 258argument. 259.Pp 260The 261.Fa class 262argument can be any of: 263.Pp 264.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent -compact 265.It Dv MODULE_CLASS_ANY 266.It Dv MODULE_CLASS_DRIVER 267Device driver 268.It Dv MODULE_CLASS_EXEC 269Executable image handler 270.It Dv MODULE_CLASS_MISC 271Miscellaneous module 272.It Dv MODULE_CLASS_SECMODEL 273Security model (see 274.Xr secmodel 9 275for more details) 276.It Dv MODULE_CLASS_VFS 277Virtual file system 278.El 279.Pp 280If the class is not 281.Dv MODULE_CLASS_ANY , 282the class of the module being loaded 283must match the requested 284.Fa class . 285Except when verifying a module's class when it is being loaded, module 286classes other than 287.Dv MODULE_CLASS_SECMODEL 288are transparent to the module subsystem. 289They are provided only for the benefit of the subsystem's clients. 290Modules with class 291.Dv MODULE_CLASS_SECMODEL 292are automatically registered with 293.Fn secmodel_register 294after being successfully loaded, and automatically deregistered with 295.Fn secmodel_deregister 296when being unloaded. 297.Pp 298The 299.Fn module_load 300routine is primarily intended as the implementation of the 301.Dv MODCTL_LOAD 302option of the 303.Xr modctl 2 304system call. 305.It Fn module_autoload "name" "class" 306Auto-load a module, making it available for automatic unloading. 307The 308.Fa name 309and 310.Fa class 311arguments are the same as for the 312.Fn module_load 313routine. 314.Pp 315The module subsystem uses a kernel thread to attempt to automatically 316unload modules a short time (currently, 10 seconds) after being loaded by 317.Fn module_autoload . 318Before the module is unloaded, its 319.Fn modcmd 320is called with the 321.Fa cmd 322argument specified as 323.Dv MODULE_CMD_AUTOUNLOAD . 324A module can prevent itself from being unloaded by returning a non-zero 325value. 326.Pp 327The 328.Fn module_autoload 329function is intended for use by kernel components to locate and load optional 330system components. 331The function is also used to load modules that are required by other modules. 332.Pp 333The directory from which the module is loaded will be searched for a file 334with the same name as the module file, but with the suffix 335.Dq Pa .plist . 336If this file is found, the prop_dictionary it contains will be loaded and 337passed to the module's 338.Fn modcmd 339routine. 340If this prop_dictionary contains a 341.Dq Pa noautoload 342property which is set to 343.Dq Pa true 344then the system will refuse to load the module. 345.It Fn module_unload "name" 346Unload a module. 347If the module's reference count is non-zero, the function returns 348.Er EBUSY . 349Otherwise, the module's 350.Fn modcmd 351routine is called with a 352.Fa cmd 353argument of 354.Dv MODULE_CMD_FINI . 355If the 356.Fn modcmd 357routine returns with an error, then the error is returned to the caller 358otherwise the module is unloaded. 359.Pp 360The reference counts of all modules that were required by this module are 361decremented, but the required modules are not unloaded by the call to 362.Fn module_unload . 363Instead, the required modules may be unloaded by subsequent calls to 364.Fn module_unload . 365.Pp 366Unloading a built-in module causes the module to be marked as disabled. 367This prevents the module from being re-loaded, except by the 368.Fn module_load 369function with the 370.Fa flags 371argument set to 372.Dv MODULE_FORCE_LOAD . 373.Pp 374The 375.Fn module_unload 376function may be called by the 377.Xr modctl 2 378system call, by the module subsystem's internal auto-unload thread, or by 379other kernel facilities. 380Generally, other kernel facilities should not be calling this function. 381.It Fn module_init_class "class" 382Load and initialize all available modules of the specified 383.Fa class . 384Any built-in modules that have not been disabled, and any modules provided 385by the boot loader are loaded. 386.It Fn module_hold "name" 387Increment the reference count of a module. 388A module cannot be unloaded if its reference count is non-zero. 389.It Fn module_rele "name" 390Decrement the reference count of a module. 391.It Fn module_find_section "name" "addr" "size" 392Find the start address and size of linker section 393.Ar name 394within a module. 395The miniroot module uses this routine to find the address and size of the 396embedded file system image. 397This routine can only examine the linker data for the module that is 398currently being initialized; it cannot examine data for any other module. 399.It Fn module_init "void" 400Initialize the module subsystem. 401Creates and initializes various data structures, locates all built-in 402modules, and establishes the sub-system's 403.Xr sysctl 8 404tree. 405.Fn module_init 406is called early in system initialization to facilitate use of security model 407modules. 408.It Fn module_start_unload_thread "void" 409Create the thread that attempts to automatically unload modules that were 410loaded via the 411.Fn module_autoload 412routine. 413The function is called only once, 414after the scheduler and timer functions are initialized. 415.It Fn module_builtin_require_force "void" 416Mark as "disabled" any built-in modules that have not been successfully 417initialized. 418Modules marked "disabled" can only be loaded if the 419.Dv MODCTL_LOAD_FORCE 420is specified. 421.Fn module_builtin_require_force 422is called near the end of system initialization, after the 423.Xr init 8 424process is created. 425.It Fn module_load_vfs_init 426The module subsystem is initialized early, long before any file systems 427are available. 428After the root file system is mounted, 429.Fn module_load_vfs_init 430is used to enable loading modules from the file system. 431Until this routine is called, modules can only be loaded if they were 432built-in to the kernel image or provided by the boot loader. 433.El 434.Sh PROGRAMMING CONSIDERATIONS 435The module subsystem is designed to be called recursively, but only within 436a single LWP. 437This permits one module's 438.Fn modcmd 439routine to load or unload other modules. 440.Pp 441Additional considerations: 442.Bl -bullet -offset indent 443.It 444A module is not permitted to load or unload itself. 445Attempts to load or unload a module from within its own 446.Fn modcmd 447routine will fail with 448.Er EEXIST 449or 450.Er EBUSY , 451respectively. 452.It 453Although a module can be loaded by using either 454.Fn module_load 455or 456.Fn module_autoload , 457it is not possible for the module's 458.Fn modcmd 459routine to distinguish between the two methods. 460Any module which needs to ensure that it does not get auto-unloaded must 461either handle the 462.Dv MODULE_CMD_AUTOUNLOAD 463command in its 464.Fn modcmd 465routine, or use 466.Fn module_hold 467to increment its reference count. 468Note however that modules loaded manually with 469.Xr modload 8 470are never auto-unloaded. 471.El 472.Sh EXAMPLES 473A set of example modules is available in the 474.Pa src/sys/modules/examples 475directory hierarchy. 476.Sh CODE REFERENCES 477The core of the kernel module implementation is in 478.Pa sys/kern/kern_module.c 479and 480.Pa sys/kern/kern_module_vfs.c . 481.Pp 482The routines for linking the module are in 483.Pa sys/kern/subr_kobj.c . 484.Pp 485The routines for reading a module from the file system are in 486.Pa sys/kern/subr_kobj_vfs.c . 487.Pp 488The header file 489.In sys/sys/module.h 490describes the public interface. 491.Pp 492In addition, each architecture is expected to provide 493.Fn kobj_machdep , 494.Fn kobj_reloc , 495and 496.Fn module_init_md . 497.Fn kobj_machdep 498is for any machine dependent actions, such as flushing caches, that are 499needed when a module is loaded or unloaded. 500.Fn kobj_reloc 501deals with resolution of relocatable symbols. 502.Fn module_init_md 503is for finding modules passed in by the boot loader. 504.Sh SEE ALSO 505.Xr modctl 2 , 506.Xr module 7 , 507.Xr intro 9lua 508.Sh HISTORY 509The kernel module subsystem first appeared in 510.Nx 5.0 . 511It replaces the 512.Dq LKM 513subsystem from earlier releases. 514.Sh AUTHORS 515.An -nosplit 516The 517.Nm 518system was written by 519.An Andrew Doran Aq Mt ad@NetBSD.org . 520This manual page was written by 521.An Paul Goyette Aq Mt pgoyette@NetBSD.org . 522