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