1.\" $NetBSD: module.9,v 1.19 2010/08/21 13:34:43 pgoyette 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 21, 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. 243.Pp 244The 245.Fn module_load 246routine is primarily intended as the implementation of the 247.Dv MODCTL_LOAD 248option of the 249.Xr modctl 2 250system call. 251.It Fn module_autoload "name" "class" 252Auto-load a module, making it available for automatic unloading. 253The 254.Fa name 255and 256.Fa class 257arguments are the same as for the 258.Fn module_load 259routine. 260.Pp 261The module subsystem uses a kernel thread to attempt to automatically 262unload modules a short time (currently, 10 seconds) after being loaded by 263.Fn module_autoload . 264Before the module is unloaded, its 265.Fn modcmd 266is called with the 267.Fa cmd 268argument specified as 269.Dv MODULE_CMD_AUTOUNLOAD . 270A module can prevent itself from being unloaded by returning a non-zero 271value. 272.Pp 273The 274.Fn module_autoload 275function is intended for use by kernel components to locate and load optional 276system components. 277The function is also used to load modules that are required by other modules. 278.It Fn module_unload "name" 279Unload a module. 280If the module's reference count is non-zero, the function returns 281.Er EBUSY . 282Otherwise, the module's 283.Fn modcmd 284routine is called with a 285.Fa cmd 286argument of 287.Dv MODULE_CMD_FINI . 288If the 289.Fn modcmd 290routine returns with an error, then the error is returned to the caller 291otherwise the module is unloaded. 292.Pp 293The reference counts of all modules that were required by this module are 294decremented, but the required modules are not unloaded by the call to 295.Fn module_unload . 296Instead, the required modules may be unloaded by subsequent calls to 297.Fn module_unload . 298.Pp 299Unloading a built-in module causes the module to be marked as disabled. 300This prevents the module from being re-loaded, except by the 301.Fn module_load 302function with the 303.Fa flags 304argument set to 305.Dv MODULE_FORCE_LOAD . 306.Pp 307The 308.Fn module_unload 309function may be called by the 310.Xr modctl 2 311system call, by the module subsystem's internal auto-unload thread, or by 312other kernel facilities. 313Generally, other kernel facilities should not be calling this function. 314.It Fn module_init_class "class" 315Load and initialize all available modules of the specified 316.Fa class . 317Any built-in modules that have not been disabled, and any modules provided 318by the boot loader are loaded. 319.It Fn module_hold "name" 320Increment the reference count of a module. 321A module cannot be unloaded if its reference count is non-zero. 322.It Fn module_rele "name" 323Decrement the reference count of a module. 324.It Fn module_find_section "name" "addr" "size" 325Find the start address and size of linker section 326.Ar name 327within a module. 328The miniroot module uses this routine to find the address and size of the 329embedded file system image. 330This routine can only examine the linker data for the module that is 331currently being initialized; it cannot examine data for any other module. 332.It Fn module_init "void" 333Initialize the module subsystem. 334Creates and initializes various data structures, locates all built-in 335modules, and establishes the sub-system's 336.Xr sysctl 8 337tree. 338.Fn module_init 339is called early in system initialization to facilitate use of security model 340modules. 341.It Fn module_start_unload_thread "void" 342Create the thread that attempts to automatically unload modules that were 343loaded via the 344.Fn module_autoload 345routine. 346.Fn module_start_unload_thread 347is called once the scheduler and timer functions are initialized. 348.It Fn module_builtin_require_force "void" 349Mark as "disabled" any built-in modules that have not been successfully 350initialized. 351Modules marked "disabled" can only be loaded if the 352.Dv MODCTL_LOAD_FORCE 353is specified. 354.Fn module_builtin_require_force 355is called near the end of system initialization, after the 356.Xr init 8 357process is created. 358.It Fn module_load_vfs_init 359The module subsystem is initialized early, long before any file systems 360are available. 361After the root file system is mounted, 362.Fn module_load_vfs_init 363is used to enable loading modules from the file system. 364Until this routine is called, modules can only be loaded if they were 365built-in to the kernel image or provided by the boot loader. 366.El 367.Sh PROGRAMMING CONSIDERATIONS 368The module subsystem is designed to be called recursively, but only within 369a single lwp. 370This permits one module's 371.Fn modcmd 372routine to load or unload other modules. 373.Pp 374A module is not permitted to load or unload itself. 375Attempts to load or unload a module from within its own 376.Fn modcmd 377routine will fail with 378.Er EEXIST 379or 380.Er EBUSY 381respectively. 382.Pp 383Although a module can be loaded by either 384.Fn module_load 385or 386.Fn module_autoload 387it is not possible for the module's 388.Fn modcmd 389routine to distinguish between the two methods. 390Any module which needs to ensure that it does not get auto-unloaded must 391either handle the 392.Dv MODULE_CMD_AUTOUNLOAD 393command in its 394.Fn modcmd 395routine, or use 396.Fn module_hold 397to increment its reference count. 398.Sh CODE REFERENCES 399This section describes places within the 400.Nx 401source tree where code implementing the kernel module loader can be found. 402All pathnames are relative to 403.Pa /usr/src . 404.Pp 405The core of the kernel module implementation is in 406.Pa sys/kern/kern_module.c 407and 408.Pa sys/kern/kern_module_vfs.c . 409.Pp 410The routines for linking the module are in 411.Pa sys/kern/subr_kobj.c . 412.Pp 413The routines for reading a module from the file system are in 414.Pa sys/kern/subr_kobj_vfs.c . 415.Pp 416The header file 417.In sys/sys/module.h 418describes the public interface. 419.Pp 420In addition, each architecture is expected to provide 421.Fn kobj_machdep , 422.Fn kobj_reloc , 423and 424.Fn module_init_md . 425.Fn kobj_machdep 426is for any machine dependent actions, such as flushing caches, that are 427needed when a module is loaded or unloaded. 428.Fn kobj_reloc 429deals with resolution of relocatable symbols. 430.Fn module_init_md 431is for finding modules passed in by the boot loader. 432.Sh SEE ALSO 433.Xr modctl 2 434.Sh HISTORY 435The kernel module subsystem first appeared in 436.Nx 5.0 . 437It replaces the 438.Dq Tn LKM 439subsystem from earlier releases. 440.Sh AUTHORS 441.An -nosplit 442The 443.Nm 444system was written by 445.An Andrew Doran Aq ad@NetBSD.org . 446This manual page was written by 447.An Paul Goyette Aq pgoyette@NetBSD.org . 448