diff options
Diffstat (limited to 'static/netbsd/man7/module.7')
| -rw-r--r-- | static/netbsd/man7/module.7 | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/static/netbsd/man7/module.7 b/static/netbsd/man7/module.7 new file mode 100644 index 00000000..4cb7425b --- /dev/null +++ b/static/netbsd/man7/module.7 @@ -0,0 +1,215 @@ +.\" $NetBSD: module.7,v 1.9 2020/07/13 13:42:51 pgoyette Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 13, 2020 +.Dt MODULE 7 +.Os +.Sh NAME +.Nm module +.Nd Kernel Modules interface +.Sh SYNOPSIS +.Cd "options MODULAR" +.Sh DESCRIPTION +Kernel modules allow the system administrator to +dynamically add and remove functionality from a running system. +This also helps software developers add +new parts of the kernel without constantly rebooting to +test their changes. +.Pp +The kernel may automatically load software modules as +needed to perform requested operations. +For example, an +.Dq xyzfs +module can be loaded automatically when an +attempt is made to mount an +.Dq xyzfs +file system. +Modules can also depend on other modules, and dependent modules are +automatically loaded. +When a module is no longer needed, it can be automatically unloaded. +.Pp +An in-kernel linker resolves symbol references between the module +and the rest of the kernel. +.Pp +The +.Nm +interface is accessed with the +.Xr modctl 2 +system call. +All common operations involving +kernel modules are handled by the +.Xr modload 8 , +.Xr modunload 8 , +and +.Xr modstat 8 +programs. +Users should never have to interact with +.Xr modctl 2 +directly. +.Sh MODULE CLASSES +.Ss Virtual File System modules +Virtual file systems may be added via the +.Nm +interface. +.Ss Device Driver modules +Many device drivers can be loaded as a kernel module. +One potential problem specific to block and character device drivers +is that the device nodes must exist for the devices to be accessed. +These need to be created manually, after the driver module has been +successfully loaded. +Most device driver modules do not +need any manual intervention to function properly. +.Ss Execution Interpreters +Execution Interpreters can be loaded to provide support for executing +binaries not normally supported by the kernel. +This also allows loading +support for executing foreign system binaries. +Execution Interpreters may require that an appropriate +emulation module also be loaded. +.Ss Miscellaneous modules +Miscellaneous modules are modules for which there are not currently +well-defined or well-used interfaces for extension. +They are provided for extension, and the user-provided module +initialization routine is expected to install the necessary "hooks" +into the rest of the operating system. +An example of a "miscellaneous module" might be a loader for +card-specific VGA drivers or alternate terminal emulations in +an appropriately layered console driver. +.Ss Security-Model modules +Alternate system security models also may be loaded using +.Nm . +.Sh EXAMPLES +The common build tool of +.Nx , +.Dq build.sh , +automatically compiles and installs most +modules during a full system build and install. +(The exceptions are some modules from external sources which, due to +licensing concerns, can be built only as separately-loaded modules.) +However, sometimes it is useful to update only modules. +The following example demonstrates one way to do this. +It is assumed that the source code is under +.Pa /usr/src , +while the object and toolchain directories are under +.Pa /usr/obj +and +.Pa /usr/tools , +respectively. +.Bd -literal -offset indent +cd /usr/src/sys/modules + +export OBJDIR=/usr/obj +export TOOLDIR=/usr/tools + +make clean +make +make install +.Ed +.Pp +Alternatively, the +.Dq build.sh +tool can be used to build and install only the modules: +.Bd -literal -offset indent +cd /usr/src +\&./build.sh -O /usr/obj -T /usr/tools modules +\&./build.sh -O /usr/obj -T /usr/tools installmodules=/ +.Ed +.Sh SEE ALSO +.Xr modctl 2 , +.Xr modload 8 , +.Xr modstat 8 , +.Xr modunload 8 , +.Xr module 9 +.Sh HISTORY +The +.Nm +facility was designed to be similar in functionality +to the loadable kernel modules facility provided by +SunOS 4.1.3. +The old +.Dv LKM +interface was replaced by +.Nm +in +.Nx 5.0 . +.Sh AUTHORS +The +.Nm +subsystem was implemented by +.An Andrew Doran +.Aq ad@netbsd.org . +.Sh CAVEATS +The +.Nm +framework is still under active development. +At least two potential caveats can be mentioned. +.Bl -enum -offset 2n +.It +Kernel modules are built to operate only with a specific version of the +.Nx +kernel. +When the kernel is updated to a new version, the contents of the +.Pa /stand/${ARCH}/${VERSION}/modules/ +directory should be updated as well. +(This location has been the subject of much discussion, and may change +in future versions of +.Nx . ) +.It +If an attempt is made to boot the operating system from a file system for +which the module is not built into the kernel, the boot may fail +with the message +.Dq "Cannot mount root, error 79" . +On certain architectures (currently, i386 and amd64), one may be able to +recover from this error by using the +.Dq "load xxxfs" +command before trying to boot. +This command is only available on newer bootloaders. +.El +.Pp +The absence of required modules or the inability of the bootloader +to load the modules are common reasons for failures to boot a +.Cd MODULAR +kernel. +It may be a good practice to maintain a non-MODULAR kernel +in the root file system for recovery purposes. +.Sh SECURITY CONSIDERATIONS +A module becomes part of the kernel once loaded. +Unlike in userland programs, fatal errors in kernel modules +may crash the operating system. +There is no memory protection between modules and the rest of the kernel. +Hence, a potential attacker with access to the +.Xr modctl 2 +system call can acquire total control over the system. +.Pp +To avoid such security risks, new modules can only be loaded when +.Pa securelevel +is less than or equal to zero, or if the kernel was built with +.Cd options INSECURE . +Refer to +.Xr secmodel_securelevel 9 +for additional details on the +.Pa securelevel . +Only use modules from trusted sources. |