1.\" $NetBSD: module.9,v 1.53 2021/07/22 01:38:45 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 July 21, 2021 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.Nm module_kernel , 43.Nm module_name , 44.Nm module_source , 45.Nm module_register_callbacks , 46.Nm module_unregister_callbacks , 47.Nm module_specific_key_create , 48.Nm module_specific_key_delete , 49.Nm module_getspecific , 50.Nm module_setspecific 51.Nd kernel module loader 52.Sh SYNOPSIS 53.In sys/module.h 54.Fn MODULE "class" "name" "required" 55.Ft int 56.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \ 57"modclass_t class" 58.Ft int 59.Fn module_autoload "const char *name" "modclass_t class" 60.Ft int 61.Fn module_unload "const char *name" 62.Ft void 63.Fn module_init_class "modclass_t class" 64.Ft void 65.Fn module_hold "module_t *module" 66.Ft void 67.Fn module_rele "module_t *module" 68.Ft int 69.Fn module_find_section "const char *" "void **" "size_t *" 70.Ft "module_t *" 71.Fn module_kernel "void" 72.Ft "const char *" 73.Fn module_name "struct module *module" 74.Ft modsrc_t 75.Fn module_source "struct module *module" 76.Ft void 77.Fn module_init "void" 78.Ft void 79.Fn module_start_unload_thread "void" 80.Ft void 81.Fn module_builtin_require_force "void" 82.Ft void 83.Fn module_load_vfs_init "void" 84.Ft "void *" 85.Fn module_register_callbacks "void (*)(struct module *)" \ 86"void (*unload)(struct module *)" 87.Ft void 88.Fn module_unregister_callbacks "void *" 89.Ft specificdata_key_t 90.Fn module_specific_key_create "specificdata_key_t *keyp" \ 91"specificdata_dtor_t dtor" 92.Ft void 93.Fn module_specific_key_delete "specificdata_key_t key" 94.Ft "void *" 95.Fn module_getspecific "module_t *mod" "specificdata_key_t key" 96.Ft "void *" 97.Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" 98.Sh DESCRIPTION 99Modules are sections of code that can be independently linked and selectively 100loaded into or unloaded from a running kernel. 101This provides a mechanism to update the module without having to relink 102the kernel and reboot. 103Modules can be loaded from within the kernel image, provided by the boot 104loader, or loaded from the file system. 105.Pp 106The 107.Nm 108subsystem includes two data types: 109.Bl -enum -offset indent 110.It 111The 112.Vt module_t 113type provides storage to describe a module. 114.It 115The 116.Vt modinfo_t 117type resides within 118.Vt module_t 119and contains module header info. 120.El 121.Pp 122The module subsystem is protected by the global 123.Va kernconfig_mutex . 124.Sh FUNCTIONS 125.Bl -tag -width abcd 126.It Fn MODULE "class" "name" "required" 127The 128.Fn MODULE 129macro creates and initializes a 130.Vt modinfo_t 131structure. 132The 133.Fa class 134argument identifies the class of module, and must be one of the following 135(note that 136.Dv MODULE_CLASS_ANY 137should not be used here): 138.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent 139.It Dv MODULE_CLASS_VFS 140The module provide a virtual file system - see 141.Xr vfs 9 142.It Dv MODULE_CLASS_DRIVER 143The module is a device driver - see 144.Xr driver 9 145.It Dv MODULE_CLASS_EXEC 146The module provides an alternate execution environment - see the various 147.Dv COMPAT_xxx 148options in 149.Xr options 4 150.It Dv MODULE_CLASS_SECMODEL 151The module provides a security model - see 152.Xr secmodel 9 153.It Dv MODULE_CLASS_BUFQ 154The module provides a buffer queue strategy - see 155.Xr bufq 9 156.It Dv MODULE_CLASS_MISC 157The module provides miscellaneous kernel services 158.El 159.Pp 160The 161.Fa name 162argument provides the name of the module. 163Loaded modules, including those that are built-in to the kernel, must all 164have unique names. 165.Pp 166The 167.Fa required 168argument is a quoted string containing a comma-separated list of module 169names that are required by this module. 170The list must not contain any white-space. 171When a module is loaded, all of its required modules are auto-loaded and 172initialized before the module itself is loaded. 173Loading of required modules is a recursive operation. 174.Pp 175If there are no required modules, this argument should be specified as 176.Dv NULL . 177.Pp 178In addition to the explicit arguments, the 179.Fn MODULE 180macro creates a reference to the module's 181.Fn modcmd 182function. 183This function is defined as: 184.Bl -tag -width modcmd -offset indent 185.It Ft modcmd_t 186.Fn xxx_modcmd "modcmd_t cmd" "void *data" 187.El 188.Pp 189(where xxx is the name of the module, from the 190.Dv MODULE 191macro). 192.Pp 193The 194.Fa cmd 195argument requests one of the following operations: 196.Bl -tag -width MODULE_CMD_AUTOUNLOAD -offset indent 197.It Dv MODULE_CMD_INIT 198Perform module-specific initialization when the module is loaded. 199.It Dv MODULE_CMD_FINI 200Perform module-specific clean-up before the module is unloaded. 201.It Dv MODULE_CMD_AUTOUNLOAD 202Notify the module that it is about to be unloaded. 203.It Dv MODULE_CMD_STAT 204Request the module to provide status information (not currently implemented). 205.El 206.Pp 207All modules' 208.Fn modcmd 209functions must implement the 210.Dv MODULE_CMD_INIT 211and 212.Dv MODULE_CMD_FINI 213commands. 214The other commands are optional, 215and should return 216.Er ENOTTY 217if not implemented. 218.Pp 219For the 220.Dv MODULE_CMD_INIT 221command, the 222.Fa data 223argument is used to pass a pointer to the module's 224.Xr prop_dictionary 3 . 225For the 226.Dv MODULE_CMD_STAT 227command, the 228.Fa data 229argument points to a buffer where the status information should be placed. 230.Pp 231The __link_set mechanism is used to enable the 232.Nm 233subsystem to locate the 234.Vt modinfo_t 235structure. 236.It Fn module_load "name" "flags" "props" "class" 237Load a module, link it into the running kernel, and call the module's 238.Fn modcmd 239routine with a 240.Fa cmd 241argument of 242.Dv MODULE_CMD_INIT . 243If the specified module requires other modules, they are loaded first; if 244any required module cannot be loaded or if any of their 245.Fn modcmd 246control routines returns a non-zero status, loading of this module and 247the specific required module will fail. 248The required modules are marked for automatic unloading. 249Thus, if the loading of the module failed, the required modules will 250be automatically unloaded after a short delay. 251.Pp 252The loader will look first for a built-in module with the specified 253.Fa name 254that has not been disabled (see 255.Fn module_unload 256below). 257If a built-in module with that 258.Fa name 259is not found, the list of modules prepared by the boot loader is searched. 260If the named module is still not found, an attempt is made to locate the 261module within the file system, provided it has been mounted by the 262initialization code. 263.Pp 264The 265.Fa flags 266argument can include: 267.Bl -tag -width MODCTL_LOAD_FORCE -offset indent 268.It Dv MODCTL_NO_PROP 269When loading a module from the file system, do not attempt to locate a 270corresponding prop_dictionary file. 271.It Dv MODCTL_LOAD_FORCE 272Force loading of disabled built-in modules and modules built for a 273different version of the operating system. 274.El 275.Pp 276The 277.Fa props 278argument points to an externalized property list which is passed to the 279module's 280.Fn modcmd 281routine. 282If a module is being loaded from the file system, and the 283.Dv MODCTL_NO_PROP 284flag is not set, the system searches for a file with the same name as the 285module file, but with the suffix 286.Dq Pa .plist . 287If this file is found, the prop_dictionary it contains is loaded and 288merged with the prop_dictionary from the 289.Fa props 290argument. 291.Pp 292The 293.Fa class 294argument can be any of: 295.Pp 296.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent -compact 297.It Dv MODULE_CLASS_ANY 298.It Dv MODULE_CLASS_DRIVER 299Device driver 300.It Dv MODULE_CLASS_EXEC 301Executable image handler 302.It Dv MODULE_CLASS_MISC 303Miscellaneous module 304.It Dv MODULE_CLASS_SECMODEL 305Security model (see 306.Xr secmodel 9 307for more details) 308.It Dv MODULE_CLASS_VFS 309Virtual file system 310.El 311.Pp 312If the class is not 313.Dv MODULE_CLASS_ANY , 314the class of the module being loaded 315must match the requested 316.Fa class . 317Except when verifying a module's class when it is being loaded, module 318classes other than 319.Dv MODULE_CLASS_SECMODEL 320are transparent to the module subsystem. 321They are provided only for the benefit of the subsystem's clients. 322Modules with class 323.Dv MODULE_CLASS_SECMODEL 324are automatically registered with 325.Fn secmodel_register 326after being successfully loaded, and automatically deregistered with 327.Fn secmodel_deregister 328when being unloaded. 329.Pp 330The 331.Fn module_load 332routine is primarily intended as the implementation of the 333.Dv MODCTL_LOAD 334option of the 335.Xr modctl 2 336system call. 337.It Fn module_autoload "name" "class" 338Auto-load a module, making it available for automatic unloading. 339The 340.Fa name 341and 342.Fa class 343arguments are the same as for the 344.Fn module_load 345routine. 346.Pp 347The module subsystem uses a kernel thread to attempt to automatically 348unload modules a short time (currently, 10 seconds) after being loaded by 349.Fn module_autoload . 350Before the module is unloaded, its 351.Fn modcmd 352is called with the 353.Fa cmd 354argument specified as 355.Dv MODULE_CMD_AUTOUNLOAD . 356A module can prevent itself from being unloaded by returning a non-zero 357value. 358.Pp 359The 360.Fn module_autoload 361function is intended for use by kernel components to locate and load optional 362system components. 363The function is also used to load modules that are required by other modules. 364.Pp 365The directory from which the module is loaded will be searched for a file 366with the same name as the module file, but with the suffix 367.Dq Pa .plist . 368If this file is found, the prop_dictionary it contains will be loaded and 369passed to the module's 370.Fn modcmd 371routine. 372If this prop_dictionary contains a 373.Dq Pa noautoload 374property which is set to 375.Dq Pa true 376then the system will refuse to load the module. 377.It Fn module_unload "name" 378Unload a module. 379If the module's reference count is non-zero, the function returns 380.Er EBUSY . 381Otherwise, the module's 382.Fn modcmd 383routine is called with a 384.Fa cmd 385argument of 386.Dv MODULE_CMD_FINI . 387If the 388.Fn modcmd 389routine returns with an error, then the error is returned to the caller 390otherwise the module is unloaded. 391.Pp 392The reference counts of all modules that were required by this module are 393decremented, but the required modules are not unloaded by the call to 394.Fn module_unload . 395Instead, the required modules may be unloaded by subsequent calls to 396.Fn module_unload . 397.Pp 398Unloading a built-in module causes the module to be marked as disabled. 399This prevents the module from being re-loaded, except by the 400.Fn module_load 401function with the 402.Fa flags 403argument set to 404.Dv MODULE_FORCE_LOAD . 405.Pp 406The 407.Fn module_unload 408function may be called by the 409.Xr modctl 2 410system call, by the module subsystem's internal auto-unload thread, or by 411other kernel facilities. 412Generally, other kernel facilities should not be calling this function. 413.It Fn module_init_class "class" 414Load and initialize all available modules of the specified 415.Fa class . 416Any built-in modules that have not been disabled, and any modules provided 417by the boot loader are loaded. 418.It Fn module_hold "module" 419Increment the reference count of a module. 420A module cannot be unloaded if its reference count is non-zero. 421.It Fn module_rele "module" 422Decrement the reference count of a module. 423.It Fn module_find_section "name" "addr" "size" 424Find the start address and size of linker section 425.Ar name 426within a module. 427The miniroot module uses this routine to find the address and size of the 428embedded file system image. 429This routine can only examine the linker data for the module that is 430currently being initialized; it cannot examine data for any other module. 431.It Fn module_kernel "void" 432Returns a pointer to a 433.Ft module_t 434structure describing the kernel module. 435.It Fn module_name module 436Returns a pointer to the module's name. 437.It Fn module_source module 438Returns the source of the module, one of 439.Dv MODULE_SOURCE_KERNEL , 440.Dv MODULE_SOURCE_BOOT , 441or 442.Dv MODULE_SOURCE_FILESYS . 443.It Fn module_init "void" 444Initialize the module subsystem. 445Creates and initializes various data structures, locates all built-in 446modules, and establishes the sub-system's 447.Xr sysctl 8 448tree. 449.Fn module_init 450is called early in system initialization to facilitate use of security model 451modules. 452.It Fn module_start_unload_thread "void" 453Create the thread that attempts to automatically unload modules that were 454loaded via the 455.Fn module_autoload 456routine. 457The function is called only once, 458after the scheduler and timer functions are initialized. 459.It Fn module_builtin_require_force "void" 460Mark as "disabled" any built-in modules that have not been successfully 461initialized. 462Modules marked "disabled" can only be loaded if the 463.Dv MODCTL_LOAD_FORCE 464is specified. 465.Fn module_builtin_require_force 466is called near the end of system initialization, after the 467.Xr init 8 468process is created. 469.It Fn module_load_vfs_init "void" 470The module subsystem is initialized early, long before any file systems 471are available. 472After the root file system is mounted, 473.Fn module_load_vfs_init "void" 474is used to enable loading modules from the file system. 475Until this routine is called, modules can only be loaded if they were 476built-in to the kernel image or provided by the boot loader. 477.It Fn module_register_callbacks "void (*load)(struct module *)" \ 478"void (*unload)(struct module *)" 479Register a new set of callbacks. 480The 481.Fa load 482callback is invoked after any module (including this module) is 483successfully loaded; the 484.Fa unload 485callback is invoked before any module is unloaded. 486Each load or unload event can result in multiple invocations of the 487callback routines. 488An opaque cookie is returned which can be passed to 489.Fn module_unregister_callbacks . 490.It Fn module_unregister_callbacks "void *opaque" 491Unregister a set of callback routines previously registered with 492.Fn module_register_callbacks . 493The 494.Fa opaque 495argument should be the return value from the previous 496.Fn module_register_callbacks 497call. 498.It Fn module_specific_key_create "specificdata_key_t *keyp" \ 499"specificdata_dtor_t dtor" 500Creates a new specificdata_key for use within the 501.Nm 502domain. 503The key identifier is returned in 504.Fa keyp . 505.It Fn module_specific_key_delete "specificdata_key_t key" 506Deletes the specified specificdata_key 507.Fa key 508from the 509.Nm 510domain. 511.It Fn module_getspecific "module_t *mod" "specificdata_key_t key" 512Retrieves the value associated with 513.Fa key 514from module 515.Fa mod . 516.It Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" 517Stores 518.Fa data 519as the value associated with 520.Fa key 521for module 522.Fa mod . 523.El 524.Sh PROGRAMMING CONSIDERATIONS 525The module subsystem is designed to be called recursively, but only within 526a single LWP. 527This permits one module's 528.Fn modcmd 529routine to load or unload other modules. 530.Pp 531Additional considerations: 532.Bl -bullet -offset indent 533.It 534A module is not permitted to load or unload itself. 535Attempts to load or unload a module from within its own 536.Fn modcmd 537routine will fail with 538.Er EEXIST 539or 540.Er EBUSY , 541respectively. 542.It 543Although a module can be loaded by using either 544.Fn module_load 545or 546.Fn module_autoload , 547it is not possible for the module's 548.Fn modcmd 549routine to distinguish between the two methods. 550Any module which needs to ensure that it does not get auto-unloaded must 551either handle the 552.Dv MODULE_CMD_AUTOUNLOAD 553command in its 554.Fn modcmd 555routine, or use 556.Fn module_hold 557to increment its reference count. 558Note however that modules loaded manually with 559.Xr modload 8 560are never auto-unloaded. 561.El 562.Sh EXAMPLES 563A set of example modules is available in the 564.Pa src/sys/modules/examples 565directory hierarchy. 566.Sh CODE REFERENCES 567The core of the kernel module implementation is in 568.Pa sys/kern/kern_module.c 569and 570.Pa sys/kern/kern_module_vfs.c . 571.Pp 572The routines for linking the module are in 573.Pa sys/kern/subr_kobj.c . 574.Pp 575The routines for reading a module from the file system are in 576.Pa sys/kern/subr_kobj_vfs.c . 577.Pp 578The header file 579.In sys/sys/module.h 580describes the public interface. 581.Pp 582In addition, each architecture is expected to provide 583.Fn kobj_machdep , 584.Fn kobj_reloc , 585and 586.Fn module_init_md . 587.Fn kobj_machdep 588is for any machine dependent actions, such as flushing caches, that are 589needed when a module is loaded or unloaded. 590.Fn kobj_reloc 591deals with resolution of relocatable symbols. 592.Fn module_init_md 593is for finding modules passed in by the boot loader. 594.Sh SEE ALSO 595.Xr modctl 2 , 596.Xr module 7 , 597.Xr specificdata 9 , 598.Xr intro 9lua 599.Sh HISTORY 600The kernel module subsystem first appeared in 601.Nx 5.0 . 602It replaces the 603.Dq LKM 604subsystem from earlier releases. 605.Sh AUTHORS 606.An -nosplit 607The 608.Nm 609system was written by 610.An Andrew Doran Aq Mt ad@NetBSD.org . 611This manual page was written by 612.An Paul Goyette Aq Mt pgoyette@NetBSD.org . 613