path: root/eclass/linux-mod-r1.eclass

# Copyright 2023-2025 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

# @ECLASS: linux-mod-r1.eclass
# @MAINTAINER:
# Ionen Wolkens <ionen@gentoo.org>
# Gentoo Kernel project <kernel@gentoo.org>
# @AUTHOR:
# Ionen Wolkens <ionen@gentoo.org>
# @SUPPORTED_EAPIS: 8
# @PROVIDES: linux-info
# @BLURB: 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.
#
# @SUBSECTION 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.
#
# @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:
#
# @CODE
# 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
# }
# @CODE
#
# Alternatively, if using the package's build system directly is
# more convenient, a typical example could be:
#
# @CODE
# 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
# }
# @CODE
#
# 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)

case ${EAPI} in
	8) ;;
	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
esac

if [[ -z ${_LINUX_MOD_R1_ECLASS} ]]; then
_LINUX_MOD_R1_ECLASS=1

inherit dist-kernel-utils edo linux-info multiprocessing toolchain-funcs

IUSE="dist-kernel modules-compress modules-sign +strip ${MODULES_OPTIONAL_IUSE}"

RDEPEND="
	sys-apps/kmod[tools]
	dist-kernel? ( virtual/dist-kernel:= )
"
DEPEND="
	virtual/linux-sources
"
BDEPEND="
	dev-util/pahole
	sys-apps/kmod[tools]
	modules-sign? (
		dev-libs/openssl
		virtual/pkgconfig
	)
"
IDEPEND="
	sys-apps/kmod[tools]
"

if [[ ${MODULES_INITRAMFS_IUSE} ]]; then
	inherit mount-boot-utils
	IUSE+=" ${MODULES_INITRAMFS_IUSE}"
	IDEPEND+="
		${MODULES_INITRAMFS_IUSE#+}? (
			sys-kernel/installkernel
		)
	"
fi

if [[ -n ${MODULES_OPTIONAL_IUSE} ]]; then
	: "${MODULES_OPTIONAL_IUSE#+}? ( | )"
	RDEPEND=${_/|/${RDEPEND}} DEPEND=${_/|/${DEPEND}} \
		BDEPEND=${_/|/${BDEPEND}} IDEPEND=${_/|/${IDEPEND}}
fi

# @ECLASS_VARIABLE: KERNEL_CHOST
# @USER_VARIABLE
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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

# @ECLASS_VARIABLE: MODULES_EXTRA_EMAKE
# @USER_VARIABLE
# @DEFAULT_UNSET
# @DESCRIPTION:
# Extra arguments to pass to emake when building modules.
# Can contain arguments with quoted spaces, e.g.
# @CODE
# ..._EMAKE="KCFLAGS='-fzomg-optimize -fsuper-strict-aliasing' ..."
# @CODE

# @ECLASS_VARIABLE: MODULES_I_WANT_FULL_CONTROL
# @USER_VARIABLE
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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.

# @ECLASS_VARIABLE: MODULES_INITRAMFS_IUSE
# @DEFAULT_UNSET
# @PRE_INHERIT
# @DESCRIPTION:
# 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.

# @ECLASS_VARIABLE: MODULES_SIGN_HASH
# @USER_VARIABLE
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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

# @ECLASS_VARIABLE: MODULES_SIGN_KEY
# @USER_VARIABLE
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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

# @ECLASS_VARIABLE: MODULES_SIGN_CERT
# @USER_VARIABLE
# @DESCRIPTION:
# 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_SIGN_CERT:=certs/signing_key.x509}"

# @ECLASS_VARIABLE: MODULES_KERNEL_MAX
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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.

# @ECLASS_VARIABLE: MODULES_KERNEL_MIN
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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.

# @ECLASS_VARIABLE: MODULES_OPTIONAL_IUSE
# @PRE_INHERIT
# @DEFAULT_UNSET
# @DESCRIPTION:
# 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.

# @ECLASS_VARIABLE: MODULES_MAKEARGS
# @OUTPUT_VARIABLE
# @DESCRIPTION:
# 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.

# @FUNCTION: linux-mod-r1_pkg_setup
# @DESCRIPTION:
# 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_pkg_setup() {
	debug-print-function ${FUNCNAME} "$@"
	_MODULES_GLOBAL[ran:pkg_setup]=1
	_modules_check_function ${#} 0 0 || return 0

	if [[ ${MODULES_INITRAMFS_IUSE} ]] &&
		use dist-kernel && use ${MODULES_INITRAMFS_IUSE#+}
	then
		# Check, but don't die because we can fix the problem and then
		# emerge --config ... to re-run installation.
		nonfatal mount-boot_check_status
	fi

	[[ ${MERGE_TYPE} != binary ]] || return 0

	_modules_check_migration

	_modules_prepare_kernel
	_modules_prepare_sign
	_modules_prepare_toolchain

	_modules_set_makeargs

	_modules_prepare_cross

	_modules_sanity_gccplugins
}

# @FUNCTION: linux-mod-r1_src_compile
# @DESCRIPTION:
# 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 bui