1.\" $NetBSD: module.9,v 1.21 2010/08/25 06:45:35 jnemeth 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 August 25, 2010 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. 179.Pp 180The 181.Fa flags 182argument can include: 183.Bl -tag -width MODCTL_LOAD_FORCE -offset indent 184.It Dv MODCTL_NO_PROP 185When loading a module from the file system, do not attempt to locate a 186corresponding prop_dictionary file. 187.It Dv MODCTL_LOAD_FORCE 188Force loading of disabled built-in modules and modules built for a 189different version of the operating system. 190.El 191.Pp 192The 193.Fa props 194argument points to an externalized property list which is passed to the 195module's 196.Fn modcmd 197routine. 198If a module is being loaded from the file system, and the 199.Dv MODCTL_NO_PROP 200flag is not set, the system searches for a file with the same name as the 201module file, but with the suffix 202.Dq Pa .prop . 203If this file is found, the prop_dictionary it contains is loaded and 204merged with the prop_dictionary from the 205.Fa props 206argument. 207.Pp 208The 209.Fa class 210argument can be any of: 211.Pp 212.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent -compact 213.It Dv MODULE_CLASS_ANY 214.It Dv MODULE_CLASS_DRIVER 215Device driver 216.It Dv MODULE_CLASS_EXEC 217Executable image handler 218.It Dv MODULE_CLASS_MISC 219Miscellaneous module 220.It Dv MODULE_CLASS_SECMODEL 221Security model (see 222.Xr secmodel 9 223for more details) 224.It Dv MODULE_CLASS_VFS 225Virtual file system 226.El 227.Pp 228If the class is not 229.Dv MODULE_CLASS_ANY , 230the class of the module being loaded 231must match the requested 232.Fa class . 233Except when verifying a module's class when it is being loaded, module 234classes other than 235.Dv MODULE_CLASS_SECMODEL 236are transparent to the module subsystem. 237They are provided only for the benefit of the subsystem's clients. 238Modules with class 239.Dv MODULE_CLASS_SECMODEL 240are automatically registered with 241.Fn secmodel_register 242after being successfully loaded, and automatically deregistered with 243.Fn secmodel_deregister 244when being unloaded. 245.Pp 246The 247.Fn module_load 248routine is primarily intended as the implementation of the 249.Dv MODCTL_LOAD 250option of the 251.Xr modctl 2 252system call. 253.It Fn module_autoload "name" "class" 254Auto-load a module, making it available for automatic unloading. 255The 256.Fa name 257and 258.Fa class 259arguments are the same as for the 260.Fn module_load 261routine. 262.Pp 263The module subsystem uses a kernel thread to attempt to automatically 264unload modules a short time (currently, 10 seconds) after being loaded by 265.Fn module_autoload . 266Before the module is unloaded, its 267.Fn modcmd 268is called with the 269.Fa cmd 270argument specified as 271.Dv MODULE_CMD_AUTOUNLOAD . 272A module can prevent itself from being unloaded by returning a non-zero 273value. 274.Pp 275The 276.Fn module_autoload 277function is intended for use by kernel components to locate and load optional 278system components. 279The function is also used to load modules that are required by other modules. 280.It Fn module_unload "name" 281Unload a module. 282If the module's reference count is non-zero, the function returns 283.Er EBUSY . 284Otherwise, the module's 285.Fn modcmd 286routine is called with a 287.Fa cmd 288argument of 289.Dv MODULE_CMD_FINI . 290If the 291.Fn modcmd 292routine returns with an error, then the error is returned to the caller 293otherwise the module is unloaded. 294.Pp 295The reference counts of all modules that were required by this module are 296decremented, but the required modules are not unloaded by the call to 297.Fn module_unload . 298Instead, the required modules may be unloaded by subsequent calls to 299.Fn module_unload . 300.Pp 301Unloading a built-in module causes the module to be marked as disabled. 302This prevents the module from being re-loaded, except by the 303.Fn module_load 304function with the 305.Fa flags 306argument set to 307.Dv MODULE_FORCE_LOAD . 308.Pp 309The 310.Fn module_unload 311function may be called by the 312.Xr modctl 2 313system call, by the module subsystem's internal auto-unload thread, or by 314other kernel facilities. 315Generally, other kernel facilities should not be calling this function. 316.It Fn module_init_class "class" 317Load and initialize all available modules of the specified 318.Fa class . 319Any built-in modules that have not been disabled, and any modules provided 320by the boot loader are loaded. 321.It Fn module_hold "name" 322Increment the reference count of a module. 323A module cannot be unloaded if its reference count is non-zero. 324.It Fn module_rele "name" 325Decrement the reference count of a module. 326.It Fn module_find_section "name" "addr" "size" 327Find the start address and size of linker section 328.Ar name 329within a module. 330The miniroot module uses this routine to find the address and size of the 331embedded file system image. 332This routine can only examine the linker data for the module that is 333currently being initialized; it cannot examine data for any other module. 334.It Fn module_init "void" 335Initialize the module subsystem. 336Creates and initializes various data structures, locates all built-in 337modules, and establishes the sub-system's 338.Xr sysctl 8 339tree. 340.Fn module_init 341is called early in system initialization to facilitate use of security model 342modules. 343.It Fn module_start_unload_thread "void" 344Create the thread that attempts to automatically unload modules that were 345loaded via the 346.Fn module_autoload 347routine. 348The function is called only once, 349after the scheduler and timer functions are initialized. 350.It Fn module_builtin_require_force "void" 351Mark as "disabled" any built-in modules that have not been successfully 352initialized. 353Modules marked "disabled" can only be loaded if the 354.Dv MODCTL_LOAD_FORCE 355is specified. 356.Fn module_builtin_require_force 357is called near the end of system initialization, after the 358.Xr init 8 359process is created. 360.It Fn module_load_vfs_init 361The module subsystem is initialized early, long before any file systems 362are available. 363After the root file system is mounted, 364.Fn module_load_vfs_init 365is used to enable loading modules from the file system. 366Until this routine is called, modules can only be loaded if they were 367built-in to the kernel image or provided by the boot loader. 368.El 369.Sh PROGRAMMING CONSIDERATIONS 370The module subsystem is designed to be called recursively, but only within 371a single LWP. 372This permits one module's 373.Fn modcmd 374routine to load or unload other modules. 375.Pp 376Additional considerations: 377.Bl -bullet -offset indent 378.It 379A module is not permitted to load or unload itself. 380Attempts to load or unload a module from within its own 381.Fn modcmd 382routine will fail with 383.Er EEXIST 384or 385.Er EBUSY , 386respectively. 387.It 388Although a module can be loaded by using either 389.Fn module_load 390or 391.Fn module_autoload , 392it is not possible for the module's 393.Fn modcmd 394routine to distinguish between the two methods. 395Any module which needs to ensure that it does not get auto-unloaded must 396either handle the 397.Dv MODULE_CMD_AUTOUNLOAD 398command in its 399.Fn modcmd 400routine, or use 401.Fn module_hold 402to increment its reference count. 403.El 404.Sh CODE REFERENCES 405This section describes places within the 406.Nx 407source tree where code implementing the kernel module loader can be found. 408All pathnames are relative to 409.Pa /usr/src . 410.Pp 411The core of the kernel module implementation is in 412.Pa sys/kern/kern_module.c 413and 414.Pa sys/kern/kern_module_vfs.c . 415.Pp 416The routines for linking the module are in 417.Pa sys/kern/subr_kobj.c . 418.Pp 419The routines for reading a module from the file system are in 420.Pa sys/kern/subr_kobj_vfs.c . 421.Pp 422The header file 423.In sys/sys/module.h 424describes the public interface. 425.Pp 426In addition, each architecture is expected to provide 427.Fn kobj_machdep , 428.Fn kobj_reloc , 429and 430.Fn module_init_md . 431.Fn kobj_machdep 432is for any machine dependent actions, such as flushing caches, that are 433needed when a module is loaded or unloaded. 434.Fn kobj_reloc 435deals with resolution of relocatable symbols. 436.Fn module_init_md 437is for finding modules passed in by the boot loader. 438.Sh SEE ALSO 439.Xr modctl 2 440.Sh HISTORY 441The kernel module subsystem first appeared in 442.Nx 5.0 . 443It replaces the 444.Dq Tn LKM 445subsystem from earlier releases. 446.Sh AUTHORS 447.An -nosplit 448The 449.Nm 450system was written by 451.An Andrew Doran Aq ad@NetBSD.org . 452This manual page was written by 453.An Paul Goyette Aq pgoyette@NetBSD.org . 454