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