LINUX-MOD-R1.ECLASS

Section: eclass-manpages (5)
Updated: Nov 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

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).

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.