Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 393 insertions, 0 deletions

diff --git a/man/man2/init_module.2 b/man/man2/init_module.2
new file mode 100644
index 0000000..98b3c5c
--- /dev/null
+++ b/man/man2/init_module.2
@@ -0,0 +1,393 @@
+.\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" A few fragments remain from a version
+.\" Copyright (C) 1996 Free Software Foundation, Inc.
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH init_module 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+init_module, finit_module \- load a kernel module
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/module.h>" "    /* Definition of " MODULE_* " constants */"
+.BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int syscall(SYS_init_module, void " module_image [. len "], \
+unsigned long " len ,
+.BI "            const char *" param_values );
+.BI "int syscall(SYS_finit_module, int " fd ,
+.BI "            const char *" param_values ", int " flags );
+.fi
+.P
+.IR Note :
+glibc provides no wrappers for these system calls,
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+.BR init_module ()
+loads an ELF image into kernel space,
+performs any necessary symbol relocations,
+initializes module parameters to values provided by the caller,
+and then runs the module's
+.I init
+function.
+This system call requires privilege.
+.P
+The
+.I module_image
+argument points to a buffer containing the binary image
+to be loaded;
+.I len
+specifies the size of that buffer.
+The module image should be a valid ELF image, built for the running kernel.
+.P
+The
+.I param_values
+argument is a string containing space-delimited specifications of the
+values for module parameters (defined inside the module using
+.BR module_param ()
+and
+.BR module_param_array ()).
+The kernel parses this string and initializes the specified
+parameters.
+Each of the parameter specifications has the form:
+.P
+.RI "        " name [\c
+.BI = value\c
+.RB [ ,\c
+.IR value ...]]
+.P
+The parameter
+.I name
+is one of those defined within the module using
+.IR module_param ()
+(see the Linux kernel source file
+.IR include/linux/moduleparam.h ).
+The parameter
+.I value
+is optional in the case of
+.I bool
+and
+.I invbool
+parameters.
+Values for array parameters are specified as a comma-separated list.
+.SS finit_module()
+The
+.BR finit_module ()
+.\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2
+.\" https://lwn.net/Articles/519010/
+system call is like
+.BR init_module (),
+but reads the module to be loaded from the file descriptor
+.IR fd .
+It is useful when the authenticity of a kernel module
+can be determined from its location in the filesystem;
+in cases where that is possible,
+the overhead of using cryptographically signed modules to
+determine the authenticity of a module can be avoided.
+The
+.I param_values
+argument is as for
+.BR init_module ().
+.P
+The
+.I flags
+argument modifies the operation of
+.BR finit_module ().
+It is a bit mask value created by ORing
+together zero or more of the following flags:
+.\" commit 2f3238aebedb243804f58d62d57244edec4149b2
+.TP
+.B MODULE_INIT_IGNORE_MODVERSIONS
+Ignore symbol version hashes.
+.TP
+.B MODULE_INIT_IGNORE_VERMAGIC
+Ignore kernel version magic.
+.TP
+.BR MODULE_INIT_COMPRESSED_FILE " (since Linux 5.17)"
+.\" commit b1ae6dc41eaaa98bb75671e0f3665bfda248c3e7
+Use in-kernel module decompression.
+.P
+There are some safety checks built into a module to ensure that
+it matches the kernel against which it is loaded.
+.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html
+.\" is dated, but informative
+These checks are recorded when the module is built and
+verified when the module is loaded.
+First, the module records a "vermagic" string containing
+the kernel version number and prominent features (such as the CPU type).
+Second, if the module was built with the
+.B CONFIG_MODVERSIONS
+configuration option enabled,
+a version hash is recorded for each symbol the module uses.
+This hash is based on the types of the arguments and return value
+for the function named by the symbol.
+In this case, the kernel version number within the
+"vermagic" string is ignored,
+as the symbol version hashes are assumed to be sufficiently reliable.
+.P
+Using the
+.B MODULE_INIT_IGNORE_VERMAGIC
+flag indicates that the "vermagic" string is to be ignored, and the
+.B MODULE_INIT_IGNORE_MODVERSIONS
+flag indicates that the symbol version hashes are to be ignored.
+If the kernel is built to permit forced loading (i.e., configured with
+.BR CONFIG_MODULE_FORCE_LOAD ),
+then loading continues, otherwise it fails with the error
+.B ENOEXEC
+as expected for malformed modules.
+.P
+If the kernel was build with
+.BR CONFIG_MODULE_DECOMPRESS ,
+the in-kernel decompression feature can be used.
+User-space code can check if the kernel supports decompression
+by reading the
+.I /sys/module/compression
+attribute.
+If the kernel supports decompression,
+the compressed file can directly be passed to
+.BR finit_module ()
+using the
+.B MODULE_INIT_COMPRESSED_FILE
+flag.
+The in-kernel module decompressor supports the following compression algorithms:
+.P
+.RS 4
+.PD 0
+.IP \[bu] 3
+.I gzip
+(since Linux 5.17)
+.IP \[bu]
+.I xz
+(since Linux 5.17)
+.IP \[bu]
+.I zstd
+.\" commit 169a58ad824d896b9e291a27193342616e651b82
+(since Linux 6.2)
+.PD
+.RE
+.P
+The kernel only implements a single decompression method.
+This is selected during module generation accordingly to the compression method
+chosen in the kernel configuration.
+.SH RETURN VALUE
+On success, these system calls return 0.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.BR EBADMSG " (since Linux 3.7)"
+Module signature is misformatted.
+.TP
+.B EBUSY
+Timeout while trying to resolve a symbol reference by this module.
+.TP
+.B EFAULT
+An address argument referred to a location that
+is outside the process's accessible address space.
+.TP
+.BR ENOKEY " (since Linux 3.7)"
+.\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1
+.\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa
+.\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7
+Module signature is invalid or
+the kernel does not have a key for this module.
+This error is returned only if the kernel was configured with
+.BR CONFIG_MODULE_SIG_FORCE ;
+if the kernel was not configured with this option,
+then an invalid or unsigned module simply taints the kernel.
+.TP
+.B ENOMEM
+Out of memory.
+.TP
+.B EPERM
+The caller was not privileged
+(did not have the
+.B CAP_SYS_MODULE
+capability),
+or module loading is disabled
+(see
+.I /proc/sys/kernel/modules_disabled
+in
+.BR proc (5)).
+.P
+The following errors may additionally occur for
+.BR init_module ():
+.TP
+.B EEXIST
+A module with this name is already loaded.
+.TP
+.B EINVAL
+.I param_values
+is invalid, or some part of the ELF image in
+.I module_image
+contains inconsistencies.
+.\" .TP
+.\" .BR EINVAL " (Linux 2.4 and earlier)"
+.\" Some
+.\" .I image
+.\" slot is filled in incorrectly,
+.\" .I image\->name
+.\" does not correspond to the original module name, some
+.\" .I image\->deps
+.\" entry does not correspond to a loaded module,
+.\" or some other similar inconsistency.
+.TP
+.B ENOEXEC
+The binary image supplied in
+.I module_image
+is not an ELF image,
+or is an ELF image that is invalid or for a different architecture.
+.P
+The following errors may additionally occur for
+.BR finit_module ():
+.TP
+.B EBADF
+The file referred to by
+.I fd
+is not opened for reading.
+.TP
+.B EFBIG
+The file referred to by
+.I fd
+is too large.
+.TP
+.B EINVAL
+.I flags
+is invalid.
+.TP
+.B EINVAL
+The decompressor sanity checks failed,
+while loading a compressed module with flag
+.B MODULE_INIT_COMPRESSED_FILE
+set.
+.TP
+.B ENOEXEC
+.I fd
+does not refer to an open file.
+.TP
+.BR EOPNOTSUPP " (since Linux 5.17)"
+The flag
+.B MODULE_INIT_COMPRESSED_FILE
+is set to load a compressed module,
+and the kernel was built without
+.BR CONFIG_MODULE_DECOMPRESS .
+.TP
+.BR ETXTBSY " (since Linux 4.7)"
+.\" commit 39d637af5aa7577f655c58b9e55587566c63a0af
+The file referred to by
+.I fd
+is opened for read-write.
+.P
+In addition to the above errors, if the module's
+.I init
+function is executed and returns an error, then
+.BR init_module ()
+or
+.BR finit_module ()
+fails and
+.I errno
+is set to the value returned by the
+.I init
+function.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.TP
+.BR finit_module ()
+Linux 3.8.
+.P
+The
+.BR init_module ()
+system call is not supported by glibc.
+No declaration is provided in glibc headers, but, through a quirk of history,
+glibc versions before glibc 2.23 did export an ABI for this system call.
+Therefore, in order to employ this system call,
+it is (before glibc 2.23) sufficient to
+manually declare the interface in your code;
+alternatively, you can invoke the system call using
+.BR syscall (2).
+.SS Linux 2.4 and earlier
+In Linux 2.4 and earlier, the
+.BR init_module ()
+system call was rather different:
+.P
+.B "    #include <linux/module.h>"
+.P
+.BI "    int init_module(const char *" name ", struct module *" image );
+.P
+(User-space applications can detect which version of
+.BR init_module ()
+is available by calling
+.BR query_module ();
+the latter call fails with the error
+.B ENOSYS
+on Linux 2.6 and later.)
+.P
+The older version of the system call
+loads the relocated module image pointed to by
+.I image
+into kernel space and runs the module's
+.I init
+function.
+The caller is responsible for providing the relocated image (since
+Linux 2.6, the
+.BR init_module ()
+system call does the relocation).
+.P
+The module image begins with a module structure and is followed by
+code and data as appropriate.
+Since Linux 2.2, the module structure is defined as follows:
+.P
+.in +4n
+.EX
+struct module {
+    unsigned long         size_of_struct;
+    struct module        *next;
+    const char           *name;
+    unsigned long         size;
+    long                  usecount;
+    unsigned long         flags;
+    unsigned int          nsyms;
+    unsigned int          ndeps;
+    struct module_symbol *syms;
+    struct module_ref    *deps;
+    struct module_ref    *refs;
+    int                 (*init)(void);
+    void                (*cleanup)(void);
+    const struct exception_table_entry *ex_table_start;
+    const struct exception_table_entry *ex_table_end;
+#ifdef __alpha__
+    unsigned long gp;
+#endif
+};
+.EE
+.in
+.P
+All of the pointer fields, with the exception of
+.I next
+and
+.IR refs ,
+are expected to point within the module body and be
+initialized as appropriate for kernel space, that is, relocated with
+the rest of the module.
+.SH NOTES
+Information about currently loaded modules can be found in
+.I /proc/modules
+and in the file trees under the per-module subdirectories under
+.IR /sys/module .
+.P
+See the Linux kernel source file
+.I include/linux/module.h
+for some useful background information.
+.SH SEE ALSO
+.BR create_module (2),
+.BR delete_module (2),
+.BR query_module (2),
+.BR lsmod (8),
+.BR modprobe (8)