1.\" $NetBSD: module.7,v 1.2 2010/12/14 18:51:56 pgoyette Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd December 14, 2010 28.Dt MODULE 7 29.Os 30.Sh NAME 31.Nm module 32.Nd Kernel Modules interface 33.Sh SYNOPSIS 34.Cd "options MODULAR" 35.Sh DESCRIPTION 36Kernel modules allow the system administrator to 37dynamically add and remove functionality from a running system. 38This ability also helps software developers to develop 39new parts of the kernel without constantly rebooting to 40test their changes. 41.Pp 42Additionally, the kernel may automatically load software modules as 43needed to perform requested operations. 44For example, an 45.Dq xyzfs 46module can be loaded automatically when an 47attempt is made to mount an 48.Dq xyzfs 49file system. 50Modules can also depend on other modules, and dependant modules are 51automatically loaded. 52When a module is no longer needed, it can be automatically unloaded. 53.Pp 54An in-kernel linker resolves symbol references between the module 55and the rest of the kernel. 56.Pp 57The 58.Nm 59interface is accessed with the 60.Xr modctl 2 61system call. 62All common operations involving 63kernel modules are handled by the 64.Xr modload 8 , 65.Xr modunload 8 , 66and 67.Xr modstat 8 68programs. 69Users should never have to interact with 70.Xr modctl 2 71directly. 72.Sh MODULE CLASSES 73.Ss Virtual File System modules 74Virtual file systems may be added via the 75.Nm 76interface. 77.Ss Device Driver modules 78Many device drivers can be loaded as a kernel module. 79One potential problem specific to block and character device drivers 80is that the device nodes must exist for the devices to be accessed. 81These need to be created manually, after the driver module has been 82successfully loaded. 83The majority of the device driver modules however does not 84need any manual intervention to function properly. 85.Ss Execution Interpreters 86Execution Interpreters can be loaded to provide support for executing 87binaries not normally supported by kernel. 88This also allows loading 89support for executing foreign system binaries. 90Execution Interpreters may require that an appropriate 91emulation module also be loaded. 92.Ss Miscellaneous modules 93Miscellaneous modules are modules for which there are not currently 94well-defined or well-used interfaces for extension. 95They are provided for extension, and the user-provided module 96initialization routine is expected to install the necessary "hooks" 97into the rest of the operating system. 98An example of a "miscellaneous module" might be a loader for 99card-specific VGA drivers or alternate terminal emulations in 100an appropriately layered console driver. 101.Ss Security-Model modules 102Alternate system security models may loaded using the 103.Nm 104facility. 105.Sh EXAMPLES 106The common build tool of 107.Nx , 108.Dq build.sh , 109automatically compiles and installs all 110modules during a full system build and install. 111Sometimes it is however useful to update only modules. 112The following example demonstrates one way to do this. 113It is assumed that the source code is under 114.Pa /usr/src , 115while the object and toolchain directories are under 116.Pa /usr/obj 117and 118.Pa /usr/tools , 119respectively. 120.Bd -literal -offset indent 121cd /usr/src/sys/modules 122 123export OBJDIR=/usr/obj 124export TOOLDIR=/usr/tools 125 126make clean 127make 128make install 129.Ed 130.Sh SEE ALSO 131.Xr modctl 2 , 132.Xr modload 8 , 133.Xr modstat 8 , 134.Xr modunload 8 , 135.Xr module 9 136.Sh HISTORY 137The 138.Nm 139facility was designed to be similar in functionality 140to the loadable kernel modules facility provided by 141.Tn "SunOS 4.1.3" . 142The old 143.Dv LKM 144interface was replaced by 145.Nm 146in 147.Nx 5.0 . 148.Sh AUTHORS 149The 150.Nm 151subsystem was implemented by 152.An Andrew Doran 153.Aq ad@netbsd.org . 154.Sh CAVEATS 155The 156.Nm 157framework is still under active development. 158At least two potential caveats can be mentioned. 159.Bl -enum -offset 2n 160.It 161Kernel modules are built to operate only with a specific version of the 162.Nx 163kernel. 164When the kernel is updated to a new version, the contents of the 165.Pa /stand/${ARCH}/${VERSION}/modules/ 166directory should be updated as well. 167(This location has been the subject of much discussion, and may change 168in future versions of 169.Nx . ) 170.It 171If an attempt is made to boot the operating system from a file system for 172which the module is not built into the kernel, the boot may fail 173with the message 174.Dq "Cannot mount root, error 79" . 175On certain architectures (currently, i386 and amd64), one may be able to 176recover from this error by using the 177.Dq "load xxxfs" 178command before trying to boot. 179This command is only available on newer bootloaders. 180.El 181.Pp 182The absence of required modules or the inability of the bootloader 183to load the modules are common reasons for failures to boot a 184.Cd MODULAR 185kernel. 186It may be a good practice to maintain a non-MODULAR kernel 187in the root file system for recovery purposes. 188.Sh SECURITY CONSIDERATIONS 189A module becomes part of the kernel once loaded. 190Compared to userland programs, all errors in the code can be fatal. 191There is no memory protection between modules and the rest of the kernel. 192Hence, a potential attacker with access to the 193.Xr modctl 2 194system call can acquire complete and total control over the system. 195.Pp 196To avoid associated security risks, new modules can only be loaded when 197.Pa securelevel 198is less than or equal to zero, or if the kernel was built with 199.Cd options INSECURE . 200Refer to 201.Xr secmodel_securelevel 9 202for additional details on the 203.Pa securelevel . 204Only use modules from trusted sources. 205