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