1.\" $NetBSD: module.9,v 1.54 2022/08/12 15:43:38 riastradh 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 by this thread, 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. 358Exception: If 359.Li kern.module.autounload_unsafe 360is set, a module that returns 361.Er ENOTTY , 362meaning it does not understand the command, may still be autounloaded. 363.Pp 364The 365.Fn module_autoload 366function is intended for use by kernel components to locate and load optional 367system components. 368The function is also used to load modules that are required by other modules. 369.Pp 370The directory from which the module is loaded will be searched for a file 371with the same name as the module file, but with the suffix 372.Dq Pa .plist . 373If this file is found, the prop_dictionary it contains will be loaded and 374passed to the module's 375.Fn modcmd 376routine. 377If this prop_dictionary contains a 378.Dq Pa noautoload 379property which is set to 380.Dq Pa true 381then the system will refuse to load the module. 382.It Fn module_unload "name" 383Unload a module. 384If the module's reference count is non-zero, the function returns 385.Er EBUSY . 386Otherwise, the module's 387.Fn modcmd 388routine is called with a 389.Fa cmd 390argument of 391.Dv MODULE_CMD_FINI . 392If the 393.Fn modcmd 394routine returns with an error, then the error is returned to the caller 395otherwise the module is unloaded. 396.Pp 397The reference counts of all modules that were required by this module are 398decremented, but the required modules are not unloaded by the call to 399.Fn module_unload . 400Instead, the required modules may be unloaded by subsequent calls to 401.Fn module_unload . 402.Pp 403Unloading a built-in module causes the module to be marked as disabled. 404This prevents the module from being re-loaded, except by the 405.Fn module_load 406function with the 407.Fa flags 408argument set to 409.Dv MODULE_FORCE_LOAD . 410.Pp 411The 412.Fn module_unload 413function may be called by the 414.Xr modctl 2 415system call, by the module subsystem's internal auto-unload thread, or by 416other kernel facilities. 417Generally, other kernel facilities should not be calling this function. 418.It Fn module_init_class "class" 419Load and initialize all available modules of the specified 420.Fa class . 421Any built-in modules that have not been disabled, and any modules provided 422by the boot loader are loaded. 423.It Fn module_hold "module" 424Increment the reference count of a module. 425A module cannot be unloaded if its reference count is non-zero. 426.It Fn module_rele "module" 427Decrement the reference count of a module. 428.It Fn module_find_section "name" "addr" "size" 429Find the start address and size of linker section 430.Ar name 431within a module. 432The miniroot module uses this routine to find the address and size of the 433embedded file system image. 434This routine can only examine the linker data for the module that is 435currently being initialized; it cannot examine data for any other module. 436.It Fn module_kernel "void" 437Returns a pointer to a 438.Ft module_t 439structure describing the kernel module. 440.It Fn module_name module 441Returns a pointer to the module's name. 442.It Fn module_source module 443Returns the source of the module, one of 444.Dv MODULE_SOURCE_KERNEL , 445.Dv MODULE_SOURCE_BOOT , 446or 447.Dv MODULE_SOURCE_FILESYS . 448.It Fn module_init "void" 449Initialize the module subsystem. 450Creates and initializes various data structures, locates all built-in 451modules, and establishes the sub-system's 452.Xr sysctl 8 453tree. 454.Fn module_init 455is called early in system initialization to facilitate use of security model 456modules. 457.It Fn module_start_unload_thread "void" 458Create the thread that attempts to automatically unload modules that were 459loaded via the 460.Fn module_autoload 461routine. 462The function is called only once, 463after the scheduler and timer functions are initialized. 464.It Fn module_builtin_require_force "void" 465Mark as "disabled" any built-in modules that have not been successfully 466initialized. 467Modules marked "disabled" can only be loaded if the 468.Dv MODCTL_LOAD_FORCE 469is specified. 470.Fn module_builtin_require_force 471is called near the end of system initialization, after the 472.Xr init 8 473process is created. 474.It Fn module_load_vfs_init "void" 475The module subsystem is initialized early, long before any file systems 476are available. 477After the root file system is mounted, 478.Fn module_load_vfs_init "void" 479is used to enable loading modules from the file system. 480Until this routine is called, modules can only be loaded if they were 481built-in to the kernel image or provided by the boot loader. 482.It Fn module_register_callbacks "void (*load)(struct module *)" \ 483"void (*unload)(struct module *)" 484Register a new set of callbacks. 485The 486.Fa load 487callback is invoked after any module (including this module) is 488successfully loaded; the 489.Fa unload 490callback is invoked before any module is unloaded. 491Each load or unload event can result in multiple invocations of the 492callback routines. 493An opaque cookie is returned which can be passed to 494.Fn module_unregister_callbacks . 495.It Fn module_unregister_callbacks "void *opaque" 496Unregister a set of callback routines previously registered with 497.Fn module_register_callbacks . 498The 499.Fa opaque 500argument should be the return value from the previous 501.Fn module_register_callbacks 502call. 503.It Fn module_specific_key_create "specificdata_key_t *keyp" \ 504"specificdata_dtor_t dtor" 505Creates a new specificdata_key for use within the 506.Nm 507domain. 508The key identifier is returned in 509.Fa keyp . 510.It Fn module_specific_key_delete "specificdata_key_t key" 511Deletes the specified specificdata_key 512.Fa key 513from the 514.Nm 515domain. 516.It Fn module_getspecific "module_t *mod" "specificdata_key_t key" 517Retrieves the value associated with 518.Fa key 519from module 520.Fa mod . 521.It Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data" 522Stores 523.Fa data 524as the value associated with 525.Fa key 526for module 527.Fa mod . 528.El 529.Sh PROGRAMMING CONSIDERATIONS 530The module subsystem is designed to be called recursively, but only within 531a single LWP. 532This permits one module's 533.Fn modcmd 534routine to load or unload other modules. 535.Pp 536Additional considerations: 537.Bl -bullet -offset indent 538.It 539A module is not permitted to load or unload itself. 540Attempts to load or unload a module from within its own 541.Fn modcmd 542routine will fail with 543.Er EEXIST 544or 545.Er EBUSY , 546respectively. 547.It 548Although a module can be loaded by using either 549.Fn module_load 550or 551.Fn module_autoload , 552it is not possible for the module's 553.Fn modcmd 554routine to distinguish between the two methods. 555Any module which needs to ensure that it does not get auto-unloaded must 556either handle the 557.Dv MODULE_CMD_AUTOUNLOAD 558command in its 559.Fn modcmd 560routine, or use 561.Fn module_hold 562to increment its reference count. 563Note however that modules loaded manually with 564.Xr modload 8 565are never auto-unloaded. 566.El 567.Sh EXAMPLES 568A set of example modules is available in the 569.Pa src/sys/modules/examples 570directory hierarchy. 571.Sh CODE REFERENCES 572The core of the kernel module implementation is in 573.Pa sys/kern/kern_module.c 574and 575.Pa sys/kern/kern_module_vfs.c . 576.Pp 577The routines for linking the module are in 578.Pa sys/kern/subr_kobj.c . 579.Pp 580The routines for reading a module from the file system are in 581.Pa sys/kern/subr_kobj_vfs.c . 582.Pp 583The header file 584.In sys/sys/module.h 585describes the public interface. 586.Pp 587In addition, each architecture is expected to provide 588.Fn kobj_machdep , 589.Fn kobj_reloc , 590and 591.Fn module_init_md . 592.Fn kobj_machdep 593is for any machine dependent actions, such as flushing caches, that are 594needed when a module is loaded or unloaded. 595.Fn kobj_reloc 596deals with resolution of relocatable symbols. 597.Fn module_init_md 598is for finding modules passed in by the boot loader. 599.Sh SEE ALSO 600.Xr modctl 2 , 601.Xr module 7 , 602.Xr specificdata 9 , 603.Xr intro 9lua 604.Sh HISTORY 605The kernel module subsystem first appeared in 606.Nx 5.0 . 607It replaces the 608.Dq LKM 609subsystem from earlier releases. 610.Sh AUTHORS 611.An -nosplit 612The 613.Nm 614system was written by 615.An Andrew Doran Aq Mt ad@NetBSD.org . 616This manual page was written by 617.An Paul Goyette Aq Mt pgoyette@NetBSD.org . 618