1.\" $NetBSD: module.9,v 1.30 2014/03/18 18:20:40 riastradh 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 October 18, 2011 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 77Two data types are relevant for 78.Nm : 79.Bl -enum -offset indent 80.It 81The 82.Vt module_t 83type provides storage to describe a module. 84.It 85The 86.Vt modinfo_t 87type resides within the module itself, and contains module header info. 88.El 89.Pp 90The module subsystem is protected by the global kernconfig_mutex. 91.Sh FUNCTIONS 92.Bl -tag -width abcd 93.It Fn MODULE "class" "name" "required" 94The 95.Fn MODULE 96macro creates and initializes a 97.Vt modinfo_t 98structure. 99In addition to the explicit arguments, the 100.Fn MODULE 101macro creates a reference to the module's 102.Fn modcmd 103function. 104This function is defined as: 105.Bl -tag -width modcmd -offset indent 106.It Ft int 107.Fn modcmd "modcmd_t cmd" "void *data" 108.El 109.Pp 110The 111.Fa cmd 112argument requests one of the following operations: 113.Bl -tag -width MODULE_CMD_AUTOUNLOAD -offset indent 114.It Dv MODULE_CMD_INIT 115Perform module-specific initialization when the module is loaded. 116.It Dv MODULE_CMD_FINI 117Perform module-specific clean-up before the module is unloaded. 118.It Dv MODULE_CMD_AUTOUNLOAD 119Notify the module that it is about to be unloaded. 120.It Dv MODULE_CMD_STAT 121Request the module to provide status information (not currently implemented). 122.El 123.Pp 124All modules' 125.Fn modcmd 126functions must implement the 127.Dv MODULE_CMD_INIT 128and 129.Dv MODULE_CMD_FINI 130commands. 131The other commands are optional, 132and should return 133.Er ENOTTY 134if not implemented. 135.Pp 136For the 137.Dv MODULE_CMD_INIT 138command, the 139.Fa data 140argument is used to pass a pointer to the module's 141.Xr prop_dictionary 3 . 142For the 143.Dv MODULE_CMD_STAT 144command, the 145.Fa data 146argument points to a buffer where the status information should be placed. 147.Pp 148The __link_set mechanism is used to enable the 149.Nm 150subsystem to locate the 151.Vt modinfo_t 152structure. 153.It Fn module_load "name" "flags" "props" "class" 154Load a module, link it into the running kernel, and call the module's 155.Fn modcmd 156routine with a 157.Fa cmd 158argument of 159.Dv MODULE_CMD_INIT . 160If the specified module requires other modules, they are loaded first; if 161any required module cannot be loaded or if any of their 162.Fn modcmd 163control routines returns a non-zero status, loading of this module and 164the specific required module will fail. 165The required modules are marked for automatic unloading. 166Thus, if the loading of the module failed, the required modules will 167be automatically unloaded after a short delay. 168.Pp 169The loader will look first for a built-in module with the specified 170.Fa name 171that has not been disabled (see 172.Fn module_unload 173below). 174If a built-in module with that 175.Fa name 176is not found, the list of modules prepared by the boot loader is searched. 177If the named module is still not found, an attempt is made to locate the 178module within the file system, provided it has been mounted by the 179initialization code. 180.Pp 181The 182.Fa flags 183argument can include: 184.Bl -tag -width MODCTL_LOAD_FORCE -offset indent 185.It Dv MODCTL_NO_PROP 186When loading a module from the file system, do not attempt to locate a 187corresponding prop_dictionary file. 188.It Dv MODCTL_LOAD_FORCE 189Force loading of disabled built-in modules and modules built for a 190different version of the operating system. 191.El 192.Pp 193The 194.Fa props 195argument points to an externalized property list which is passed to the 196module's 197.Fn modcmd 198routine. 199If a module is being loaded from the file system, and the 200.Dv MODCTL_NO_PROP 201flag is not set, the system searches for a file with the same name as the 202module file, but with the suffix 203.Dq Pa .plist . 204If this file is found, the prop_dictionary it contains is loaded and 205merged with the prop_dictionary from the 206.Fa props 207argument. 208.Pp 209The 210.Fa class 211argument can be any of: 212.Pp 213.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent -compact 214.It Dv MODULE_CLASS_ANY 215.It Dv MODULE_CLASS_DRIVER 216Device driver 217.It Dv MODULE_CLASS_EXEC 218Executable image handler 219.It Dv MODULE_CLASS_MISC 220Miscellaneous module 221.It Dv MODULE_CLASS_SECMODEL 222Security model (see 223.Xr secmodel 9 224for more details) 225.It Dv MODULE_CLASS_VFS 226Virtual file system 227.El 228.Pp 229If the class is not 230.Dv MODULE_CLASS_ANY , 231the class of the module being loaded 232must match the requested 233.Fa class . 234Except when verifying a module's class when it is being loaded, module 235classes other than 236.Dv MODULE_CLASS_SECMODEL 237are transparent to the module subsystem. 238They are provided only for the benefit of the subsystem's clients. 239Modules with class 240.Dv MODULE_CLASS_SECMODEL 241are automatically registered with 242.Fn secmodel_register 243after being successfully loaded, and automatically deregistered with 244.Fn secmodel_deregister 245when being unloaded. 246.Pp 247The 248.Fn module_load 249routine is primarily intended as the implementation of the 250.Dv MODCTL_LOAD 251option of the 252.Xr modctl 2 253system call. 254.It Fn module_autoload "name" "class" 255Auto-load a module, making it available for automatic unloading. 256The 257.Fa name 258and 259.Fa class 260arguments are the same as for the 261.Fn module_load 262routine. 263.Pp 264The module subsystem uses a kernel thread to attempt to automatically 265unload modules a short time (currently, 10 seconds) after being loaded by 266.Fn module_autoload . 267Before the module is unloaded, its 268.Fn modcmd 269is called with the 270.Fa cmd 271argument specified as 272.Dv MODULE_CMD_AUTOUNLOAD . 273A module can prevent itself from being unloaded by returning a non-zero 274value. 275.Pp 276The 277.Fn module_autoload 278function is intended for use by kernel components to locate and load optional 279system components. 280The function is also used to load modules that are required by other modules. 281.Pp 282The directory from which the module is loaded will be searched for a file 283with the same name as the module file, but with the suffix 284.Dq Pa .plist . 285If this file is found, the prop_dictionary it contains will be loaded and 286passed to the module's 287.Fn modcmd 288routine. 289If this prop_dictionary contains a 290.Dq Pa noautoload 291property which is set to 292.Dq Pa true 293then the system will refuse to load the module. 294.It Fn module_unload "name" 295Unload a module. 296If the module's reference count is non-zero, the function returns 297.Er EBUSY . 298Otherwise, the module's 299.Fn modcmd 300routine is called with a 301.Fa cmd 302argument of 303.Dv MODULE_CMD_FINI . 304If the 305.Fn modcmd 306routine returns with an error, then the error is returned to the caller 307otherwise the module is unloaded. 308.Pp 309The reference counts of all modules that were required by this module are 310decremented, but the required modules are not unloaded by the call to 311.Fn module_unload . 312Instead, the required modules may be unloaded by subsequent calls to 313.Fn module_unload . 314.Pp 315Unloading a built-in module causes the module to be marked as disabled. 316This prevents the module from being re-loaded, except by the 317.Fn module_load 318function with the 319.Fa flags 320argument set to 321.Dv MODULE_FORCE_LOAD . 322.Pp 323The 324.Fn module_unload 325function may be called by the 326.Xr modctl 2 327system call, by the module subsystem's internal auto-unload thread, or by 328other kernel facilities. 329Generally, other kernel facilities should not be calling this function. 330.It Fn module_init_class "class" 331Load and initialize all available modules of the specified 332.Fa class . 333Any built-in modules that have not been disabled, and any modules provided 334by the boot loader are loaded. 335.It Fn module_hold "name" 336Increment the reference count of a module. 337A module cannot be unloaded if its reference count is non-zero. 338.It Fn module_rele "name" 339Decrement the reference count of a module. 340.It Fn module_find_section "name" "addr" "size" 341Find the start address and size of linker section 342.Ar name 343within a module. 344The miniroot module uses this routine to find the address and size of the 345embedded file system image. 346This routine can only examine the linker data for the module that is 347currently being initialized; it cannot examine data for any other module. 348.It Fn module_init "void" 349Initialize the module subsystem. 350Creates and initializes various data structures, locates all built-in 351modules, and establishes the sub-system's 352.Xr sysctl 8 353tree. 354.Fn module_init 355is called early in system initialization to facilitate use of security model 356modules. 357.It Fn module_start_unload_thread "void" 358Create the thread that attempts to automatically unload modules that were 359loaded via the 360.Fn module_autoload 361routine. 362The function is called only once, 363after the scheduler and timer functions are initialized. 364.It Fn module_builtin_require_force "void" 365Mark as "disabled" any built-in modules that have not been successfully 366initialized. 367Modules marked "disabled" can only be loaded if the 368.Dv MODCTL_LOAD_FORCE 369is specified. 370.Fn module_builtin_require_force 371is called near the end of system initialization, after the 372.Xr init 8 373process is created. 374.It Fn module_load_vfs_init 375The module subsystem is initialized early, long before any file systems 376are available. 377After the root file system is mounted, 378.Fn module_load_vfs_init 379is used to enable loading modules from the file system. 380Until this routine is called, modules can only be loaded if they were 381built-in to the kernel image or provided by the boot loader. 382.El 383.Sh PROGRAMMING CONSIDERATIONS 384The module subsystem is designed to be called recursively, but only within 385a single LWP. 386This permits one module's 387.Fn modcmd 388routine to load or unload other modules. 389.Pp 390Additional considerations: 391.Bl -bullet -offset indent 392.It 393A module is not permitted to load or unload itself. 394Attempts to load or unload a module from within its own 395.Fn modcmd 396routine will fail with 397.Er EEXIST 398or 399.Er EBUSY , 400respectively. 401.It 402Although a module can be loaded by using either 403.Fn module_load 404or 405.Fn module_autoload , 406it is not possible for the module's 407.Fn modcmd 408routine to distinguish between the two methods. 409Any module which needs to ensure that it does not get auto-unloaded must 410either handle the 411.Dv MODULE_CMD_AUTOUNLOAD 412command in its 413.Fn modcmd 414routine, or use 415.Fn module_hold 416to increment its reference count. 417Note however that modules loaded manually with 418.Xr modload 8 419are never auto-unloaded. 420.El 421.Sh CODE REFERENCES 422The core of the kernel module implementation is in 423.Pa sys/kern/kern_module.c 424and 425.Pa sys/kern/kern_module_vfs.c . 426.Pp 427The routines for linking the module are in 428.Pa sys/kern/subr_kobj.c . 429.Pp 430The routines for reading a module from the file system are in 431.Pa sys/kern/subr_kobj_vfs.c . 432.Pp 433The header file 434.In sys/sys/module.h 435describes the public interface. 436.Pp 437In addition, each architecture is expected to provide 438.Fn kobj_machdep , 439.Fn kobj_reloc , 440and 441.Fn module_init_md . 442.Fn kobj_machdep 443is for any machine dependent actions, such as flushing caches, that are 444needed when a module is loaded or unloaded. 445.Fn kobj_reloc 446deals with resolution of relocatable symbols. 447.Fn module_init_md 448is for finding modules passed in by the boot loader. 449.Sh SEE ALSO 450.Xr modctl 2 , 451.Xr module 7 452.Sh HISTORY 453The kernel module subsystem first appeared in 454.Nx 5.0 . 455It replaces the 456.Dq Tn LKM 457subsystem from earlier releases. 458.Sh AUTHORS 459.An -nosplit 460The 461.Nm 462system was written by 463.An Andrew Doran Aq Mt ad@NetBSD.org . 464This manual page was written by 465.An Paul Goyette Aq Mt pgoyette@NetBSD.org . 466