LINUX-MOD-R1.ECLASS

Section: eclass-manpages (5)
Updated: Jul 2024
Index Return to Main Contents

NAME

linux-mod-r1.eclass - Functions for installing out-of-tree Linux kernel modules

DESCRIPTION

See the linux-mod-r1_src_compile function documentation for in-depth usage, and see the example further down for a quick overview.

linux-mod -> linux-mod-r1 migration notes


 0. Define a src_compile if missing, local variables below go there.
 1. MODULE_NAMES="name(libdir:srcdir:objdir)"
    BUILD_TARGETS="target"
      -> local modlist=( name=libdir:srcdir:objdir:target(s) )
    - try without :target first, it is now almost always unnecessary
    - srcdir defaults to the current directory, and note that paths
      can be relative to that (should typically *not* pass ${S})
 2. BUILD_PARAMS and/or BUILD_FIXES
      -> local modargs=( VAR="${KV_OUT_DIR}" ... )
    - CC/LD and similar are unneeded, always passed (V=1 too)
    - eval (aka eval "${BUILD_PARAMS}") is /not/ used for this anymore
 3. s/linux-mod_/linux-mod-r1/g
 4. _preinst+_postrm can be dropped, keep linux-mod-r1_pkg_postinst
 5. linux-mod-r1_src_install now runs einstalldocs, adjust as needed
 6. if *not* using linux-mod-r1_src_compile/install, then refer to
    the eclass' 2nd example and ensure using modules_post_process
 7. If any, clang<->gcc switching custom workarounds can be dropped
 8. See MODULES_KERNEL_MAX/_MIN if had or need kernel version checks.

Not an exhaustive list, verify that no installed files are missing after. Look for "command not found" errors in the build log too.

Revision bumps are not strictly needed to migrate unless want to keep the old as fallback for regressions, kernel upgrades or the new IUSE=+strip will typically cause rebuilds either way.

SUPPORTED EAPIS

8

TRANSITIVELY PROVIDED ECLASSES

linux-info

EXAMPLE

If source directory S had a layout such as:
 - Makefile (builds a gentoo.ko in current directory)
 - gamepad/Makefile (want to install to kernel/drivers/hid)
 - gamepad/obj/ (the built gamepad.ko ends up here)

...and the Makefile uses the NIH_SOURCE variable to find where the kernel build directory is (aka KV_OUT_DIR, see linux-info.eclass)

then:

CONFIG_CHECK="INPUT_FF_MEMLESS" # gamepad needs it to rumble
MODULES_KERNEL_MIN=5.4 # needs features introduced in 5.4

src_compile() {
    local modlist=(
        gentoo
        gamepad=kernel/drivers/hid:gamepad:gamepad/obj
    )
    local modargs=( NIH_SOURCE="${KV_OUT_DIR}" )

    linux-mod-r1_src_compile
}

Alternatively, if using the package's build system directly is more convenient, a typical example could be:

src_compile() {
    MODULES_MAKEARGS+=(
        NIH_KDIR="${KV_OUT_DIR}"
        NIH_KSRC="${KV_DIR}"
    )

    emake "${MODULES_MAKEARGS[@]}"
}

src_install() {
    emake "${MODULES_MAKEARGS[@]}" DESTDIR="${ED}" install
    modules_post_process # strip->sign->compress

    einstalldocs
}

Some extra make variables may be of interest:
 - INSTALL_MOD_PATH: sometime used as DESTDIR
 - INSTALL_MOD_DIR: equivalent to linux_moduleinto

MODULES_MAKEARGS is set by the eclass to handle toolchain and, when installing, also attempts to disable automatic stripping, compression, signing, and depmod to let the eclass handle it.

linux_domodule can alternatively be used to install a single module.

(remember to ensure that linux-mod-r1_pkg_postinst is ran for depmod)

FUNCTIONS

linux-mod-r1_pkg_setup
Required before using other functions from this eclass, and will:
 1. run linux-info_pkg_setup (see linux-info.eclass)
 -> implies processing CONFIG_CHECK, and providing KV_ variables
   (MODULES and TRIM_UNUSED_KSYMS are always checked)
 2. prepare toolchain to match the kernel
 -> sets KERNEL_{CHOST,CC,CXX,LD,AR,NM,OBJCOPY,OBJDUMP,READELF,STRIP}
 -> also sets MODULES_MAKEARGS array with, e.g. CC="${KERNEL_CC}"
   (normally these should not be used directly, for custom builds)
 3. perform various sanity checks to fail early on issues
linux-mod-r1_src_compile
Builds modules, see the eclass' example for a quick overview. Uses the variables modlist and modargs as described below:

* local modlist=( ... ) - list of modules to build, set as:


    module-name=install-dir:source-dir:build-dir:make-target

> module-name: Resulting name, aka <module-name>.ko (required).

> install-dir: Kernel modules sub-directory to install the module to (/lib/modules/version/<install-dir>/name.ko). Will be used when run linux-mod-r1_src_install. May want to consider the values of INSTALL_MOD_DIR(Makefile) or DEST_MODULE_LOCATION(dkms.conf) if it exists, but it can be anything.
 -> Default: extra

Warning: Changing this location may leave stale modules until a kernel upgrade as the package manager does not typically delete old modules and only does overwrite on rebuilds.

> source-dir: Directory containing the Makefile to build the module. Path can be relative to the current directory or absolute.
 -> Default: current directory

> build-dir: Directory that will hold the built module-name.ko.
 -> Default: same as source-dir's value

> make-target: Almost always unneeded but, if defaults are not right, then can specify the Makefile's target(s) to build the module/extras. Multiple targets can be used with spaces, e.g. :"first second".
 -> Default: specially tries modules, module, <name>.ko, default, all, empty target, and runs the first found usable

Missing elements results in defaults being used, e.g. this is valid:
  modlist=( name1 name2=:source name3=install::build )

* local modargs=( ... ) - extra arguments to pass to emake

Makefile should notably be inspected for which variable it uses to find the kernel's build directory then, e.g. KDIR="${KV_OUT_DIR}" as appropriate. Note that typically want to pass KV_OUT_DIR(build) rather than KV_DIR(sources) if not both. This allows users to do out-of-source kernel builds and still build modules.

Passing common toolchain variables such as CC or LD is not needed here as they are passed by default.

---

Allowed to be called multiple times with a different modlist if need different make arguments per modules or intermediate steps -- albeit, if atypical, may want to build manually (see eclass' example).

linux-mod-r1_src_install
Installs modules built by linux-mod-r1_src_compile using linux_domodule, then runs modules_post_process and einstalldocs.
linux-mod-r1_pkg_postinst
Updates module dependencies using depmod.
linux_domodule <module>...
Installs Linux modules (.ko files).

See also linux_moduleinto.

linux_moduleinto <install-dir>
Directory to install modules into when calling linux_domodule. Relative to kernel modules path as in: ${ED}/lib/modules/${KV_FULL}/<install-dir>

Can contain subdirectories, e.g. kernel/fs.

If not called, defaults to "extra". On the kernel build system, this is like setting INSTALL_MOD_DIR which has the same default for external modules.

modules_post_process [<path>]
Strip, sign, verify, and compress all .ko modules found under <path>. Should typically *not* be called directly as it will be run by linux-mod-r1_src_install. This is intended for use when modules were installed some other way.

<path> should exist under ${ED}. Defaults to /lib/modules/${KV_FULL}.

Filenames may change due to compression, so any operations on these should be performed prior.

Warning: This will abort if no modules are found, which can happen if modules were unexpectedly pre-compressed possibly due to using make install without passing MODULES_MAKEARGS to disable it.

ECLASS VARIABLES

KERNEL_CHOST (USER VARIABLE)
Can be set to the CHOST value to use when selecting the toolchain for building kernel modules. This is similar to setting the kernel build system's CROSS_COMPILE variable minus the trailing dash.

If this does not auto-select the desired toolchain, finer control can be achieved by setting the not directly documented (but valid) variables:

KERNEL_{CC,CXX,LD,AR,NM,OBJCOPY,OBJDUMP,READELF,STRIP}

If in doubt, do not set any of this.

Default if unset: auto-detection, typically same as the current CHOST

MODULES_EXTRA_EMAKE (USER VARIABLE)
Extra arguments to pass to emake when building modules. Can contain arguments with quoted spaces, e.g.
..._EMAKE="KCFLAGS='-fzomg-optimize -fsuper-strict-aliasing' ..."
MODULES_I_WANT_FULL_CONTROL (USER VARIABLE)
When set to a non-empty value, disables passing most of the eclass' toolchain defaults to emake when building modules. Basic eclass requirements, ebuilds' modargs, and users' MODULES_EXTRA_EMAKE are still used.

Primarily intended for expert users with modified kernel Makefiles that want the Makefile's values to be used by default.

May want to look at KERNEL_CHOST before considering this.

MODULES_INITRAMFS_IUSE (SET BEFORE INHERIT)
If set, adds the specified USE flag. When this flag is enabled the installed kernel modules are registered for inclusion in the dracut initramfs. Additionally, if distribution kernels are used (USE="dist-kernel") then these kernels are re-installed.

The typical recommended value is "initramfs" or "+initramfs" (global IUSE).

If MODULES_INITRAMFS_IUSE is not set, or the specified flag is not enabled, then the installed kernel modules are omitted from the dracut initramfs.

MODULES_SIGN_HASH (USER VARIABLE)
Used with USE=modules-sign. Can be set to hash algorithm to use during signature generation.

Rather than set this, it is recommended to select using the kernel's configuration to ensure proper support (e.g. CONFIG_MODULE_SIG_SHA256), and then it will be auto-detected here.

Valid values: sha512,sha384,sha256,sha224,sha1

Default if unset: kernel CONFIG_MODULE_SIG_HASH's value

MODULES_SIGN_KEY (USER VARIABLE)
Used with USE=modules-sign. Can be set to the path of the private key in PEM format to use, or a PKCS#11 URI.

If path is relative (e.g. "certs/name.pem"), it is assumed to be relative to the kernel build directory being used.

If the key requires a passphrase or PIN, the used kernel sign-file utility recognizes the KBUILD_SIGN_PIN environment variable. Be warned that the package manager may store this value in binary packages, database files, temporary files, and possibly logs. This eclass unsets the variable after use to mitigate the issue (notably for shared binary packages), but use this with care.

Default if unset: kernel CONFIG_MODULE_SIG_KEY's value which itself defaults to certs/signing_key.pem

MODULES_SIGN_CERT ?= certs/signing_key.x509 (USER VARIABLE)
Used with USE=modules-sign. Can be set to the path of the X.509 public key certificate to use.

If path is relative (e.g. "certs/name.x509"), it is assumed to be relative to the kernel build directory being used.

MODULES_KERNEL_MAX
If set to a kernel version (format: 1, 1.2, or 1.2.3), will print a warning if the used version is greater than (ver_test -gt) to this value using the same amount of version components (i.e. MAX=1.2 allows 1.2.3, but MAX=1.2.2 does not).

This should *only* be used for modules that are known to break frequently on kernel upgrades. If setting this to a non-LTS kernel, then should also take care to test and update this value regularly with new major kernel releases not to let the warning become stale and ignored by users.

Not fatal to allow users to try or self-patch easily, but the (large) warning is difficult to miss. If need a fatal check for more serious issues (e.g. runtime filesystem corruption), please do it manually.

This is intended to reduce the amount of bug reports for recurring expected issues that can be easily mitigated by using LTS kernels and waiting for new releases.

If used, must be set before linux-mod-r1_pkg_setup is called.

MODULES_KERNEL_MIN
If set to a kernel version (format: 1, 1.2, or 1.2.3), will abort if the used version is less than (ver_test -lt) this value.

Should only be used if known broken, or if upstream recommends a sane minimum. Not particularly necessary for kernels that are no longer in the tree.

If used, must be set before linux-mod-r1_pkg_setup is called.

MODULES_OPTIONAL_IUSE (SET BEFORE INHERIT)
May contain a single flag to be added to IUSE optionally prefixed with a + sign to enable it by default. Doing so makes *all* of linux-mod-r1's functions and dependencies a no-op unless the flag is enabled. This includes phases, e.g. linux-mod-r1_pkg_setup will not process CONFIG_CHECK unless the flag is set.

The typical recommended value is "+modules" (global IUSE).

Note that modules being optional can be useful even if user space tools require them (e.g. installing in a chroot or prefix when the modules are loaded on the host, saves setting up linux sources). However, if tools are non-trivial to build, it may be preferable to split into two packages than use this variable due to requiring rebuilds every kernel upgrades.

MODULES_MAKEARGS (GENERATED BY ECLASS)
Will be set after linux-mod-r1_pkg_setup has been called. Contains arguments that should be passed to emake when building or installing modules.

Modifying this variable is acceptable (e.g. to append kernel source arguments) but, if using linux-mod-r1_src_compile, setting modargs is the intended method seen as cleaner and less error-prone.

AUTHORS

Ionen Wolkens <ionen@gentoo.org>

MAINTAINERS

Ionen Wolkens <ionen@gentoo.org>
Gentoo Kernel project <kernel@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

linux-mod-r1.eclass

SEE ALSO

ebuild(5)
https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/linux-mod-r1.eclass


Index

NAME
DESCRIPTION
linux-mod -> linux-mod-r1 migration notes
SUPPORTED EAPIS
TRANSITIVELY PROVIDED ECLASSES
EXAMPLE
FUNCTIONS
ECLASS VARIABLES
AUTHORS
MAINTAINERS
REPORTING BUGS
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 03:27:01 GMT, July 21, 2024