From 45d4cecb47f339386527c5a614b28ee4a983fc1b Mon Sep 17 00:00:00 2001 From: Daniel Drake Date: Fri, 31 Oct 2008 22:24:55 +0000 Subject: add some fantastic documentation from Fabio Rossi in bug #217560 --- eclass/linux-mod.eclass | 252 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 187 insertions(+), 65 deletions(-) (limited to 'eclass/linux-mod.eclass') diff --git a/eclass/linux-mod.eclass b/eclass/linux-mod.eclass index 8a085e197473..1d83981c5d8d 100644 --- a/eclass/linux-mod.eclass +++ b/eclass/linux-mod.eclass @@ -1,47 +1,60 @@ # Copyright 1999-2004 Gentoo Foundation # Distributed under the terms of the GNU General Public License v2 -# $Header: /var/cvsroot/gentoo-x86/eclass/linux-mod.eclass,v 1.85 2008/10/31 21:25:56 dsd Exp $ +# $Header: /var/cvsroot/gentoo-x86/eclass/linux-mod.eclass,v 1.86 2008/10/31 22:24:55 dsd Exp $ -# Description: This eclass is used to interface with linux-info in such a way -# to provide the functionality required and initial functions -# required to install external modules against a kernel source -# tree. -# # Author(s): John Mylchreest , # Stefan Schweizer # Maintainer: kernel-misc@gentoo.org # # Please direct your bugs to the current eclass maintainer :) +# @ECLASS: linux-mod.eclass +# @MAINTAINER: +# kernel-misc@gentoo.org +# @BLURB: It provides the functionality required to install external modules against a kernel source tree. +# @DESCRIPTION: +# This eclass is used to interface with linux-info.eclass in such a way +# to provide the functionality and initial functions +# required to install external modules against a kernel source +# tree. + # A Couple of env vars are available to effect usage of this eclass # These are as follows: -# -# Env Var Option Default Description -# KERNEL_DIR /usr/src/linux The directory containing kernel -# the target kernel sources. -# ECONF_PARAMS The parameters to pass to econf. -# If this is not set, then econf -# isn't run. -# BUILD_PARAMS The parameters to pass to emake. -# BUILD_TARGETS clean modules The build targets to pass to -# make. -# MODULE_NAMES This is the modules which are -# to be built automatically using -# the default pkg_compile/install. -# They are explained properly -# below. It will only make -# BUILD_TARGETS once in any -# directory. - -# MODULE_NAMES - Detailed Overview + +# @ECLASS-VARIABLE: KERNEL_DIR +# @DESCRIPTION: +# A string containing the directory of the target kernel sources. The default value is +# "/usr/src/linux" + +# @ECLASS-VARIABLE: ECONF_PARAMS +# @DESCRIPTION: +# It's a string containing the parameters to pass to econf. +# If this is not set, then econf isn't run. + +# @ECLASS-VARIABLE: BUILD_PARAMS +# @DESCRIPTION: +# It's a string with the parameters to pass to emake. + +# @ECLASS-VARIABLE: BUILD_TARGETS +# @DESCRIPTION: +# It's a string with the build targets to pass to make. The default value is "clean modules" + +# @ECLASS-VARIABLE: MODULE_NAMES +# @DESCRIPTION: +# It's a string containing the modules to be built automatically using the default +# src_compile/src_install. It will only make ${BUILD_TARGETS} once in any directory. + # # The structure of each MODULE_NAMES entry is as follows: -# modulename(libdir:srcdir:objdir) # -# modulename = name of the module file excluding the .ko -# libdir = place in system modules directory where module is installed: -# srcdir = place for ebuild to cd to before running make -# objdir = place the .ko and objects are located after make runs +# modulename(libdir:srcdir:objdir) +# +# where: +# +# modulename = name of the module file excluding the .ko +# libdir = place in system modules directory where module is installed: +# srcdir = place for ebuild to cd to before running make +# objdir = place the .ko and objects are located after make runs # # To get an idea of how these variables are used, here's a few lines # of code from around line 540 in this eclass: @@ -51,47 +64,67 @@ # insinto /lib/modules/${KV_FULL}/${libdir} # doins ${modulename}.${KV_OBJ} || die "doins ${modulename}.${KV_OBJ} failed" # -# for example: -# MODULE_NAMES="module_pci(pci:${S}/pci:${S}) module_usb(usb:${S}/usb:${S})" +# For example: +# MODULE_NAMES="module_pci(pci:${S}/pci:${S}) module_usb(usb:${S}/usb:${S})" # # what this would do is -# cd ${S}/pci -# make ${BUILD_PARAMS} ${BUILD_TARGETS} -# cd ${S} -# insinto /lib/modules/${KV_FULL}/pci -# doins module_pci.${KV_OBJ} # -# cd ${S}/usb -# make ${BUILD_PARAMS} ${BUILD_TARGETS} -# cd ${S} -# insinto /lib/modules/${KV_FULL}/usb -# doins module_usb.${KV_OBJ} +# cd "${S}"/pci +# make ${BUILD_PARAMS} ${BUILD_TARGETS} +# cd "${S}" +# insinto /lib/modules/${KV_FULL}/pci +# doins module_pci.${KV_OBJ} # -# if the srcdir isnt specified, it assumes ${S} -# if the libdir isnt specified, it assumes misc. -# if the objdir isnt specified, it assumes srcdir +# cd "${S}"/usb +# make ${BUILD_PARAMS} ${BUILD_TARGETS} +# cd "${S}" +# insinto /lib/modules/${KV_FULL}/usb +# doins module_usb.${KV_OBJ} # There is also support for automated modprobe.d/modules.d(2.4) file generation. # This can be explicitly enabled by setting any of the following variables. + +# @ECLASS-VARIABLE: MODULESD__ENABLED +# @DESCRIPTION: +# This is used to disable the modprobe.d/modules.d file generation otherwise the file will be +# always generated (unless no MODULESD__* variable is provided). Set to "no" to disable +# the generation of the file and the installation of the documentation. + +# @ECLASS-VARIABLE: MODULESD__EXAMPLES +# @DESCRIPTION: +# This is a bash array containing a list of examples which should +# be used. If you want us to try and take a guess set this to "guess". # +# For each array_component it's added an options line in the modprobe.d/modules.d file # -# MODULESD_${modulename}_ENABLED This enables the modules.d file -# generation even if we dont -# specify any additional info. -# MODULESD_${modulename}_EXAMPLES This is a bash array containing -# a list of examples which should -# be used. If you want us to try and -# take a guess. Set this to "guess" -# MODULESD_${modulename}_ALIASES This is a bash array containing -# a list of associated aliases. -# MODULESD_${modulename}_ADDITIONS This is a bash array containing -# A list of additional things to -# add to the bottom of the file. -# This can be absolutely anything. -# Each entry is a new line. -# MODULES_${modulename}_DOCS This is a string list which contains -# the full path to any associated -# documents for $modulename +# options array_component +# +# where array_component is " options" (see modprobe.conf(5)) + +# @ECLASS-VARIABLE: MODULESD__ALIASES +# @DESCRIPTION: +# This is a bash array containing a list of associated aliases. +# +# For each array_component it's added an alias line in the modprobe.d/modules.d file +# +# alias array_component +# +# where array_component is "wildcard " (see modprobe.conf(5)) + +# @ECLASS-VARIABLE: MODULESD__ADDITIONS +# @DESCRIPTION: +# This is a bash array containing a list of additional things to +# add to the bottom of the file. This can be absolutely anything. +# Each entry is a new line. + +# @ECLASS-VARIABLE: MODULESD__DOCS +# @DESCRIPTION: +# This is a string list which contains the full path to any associated +# documents for . These files are installed in the live tree. + +# @ECLASS-VARIABLE: KV_OBJ +# @DESCRIPTION: +# It's a read-only variable. It contains the extension of the kernel modules. # The order of these is important as both of linux-info and eutils contain # set_arch_to_kernel and set_arch_to_portage functions and the ones in eutils @@ -150,6 +183,10 @@ check_vermagic() { fi } +# @FUNCTION: use_m +# @RETURN: true or false +# @DESCRIPTION: +# It checks if the kernel version is greater than 2.6.5. use_m() { debug-print-function ${FUNCNAME} $* @@ -162,6 +199,10 @@ use_m() { return 0 || return 1 } +# @FUNCTION: convert_to_m +# @USAGE: /path/to/the/file +# @DESCRIPTION: +# It converts a file (e.g. a makefile) to use M= instead of SUBDIRS= convert_to_m() { debug-print-function ${FUNCNAME} $* @@ -175,6 +216,11 @@ convert_to_m() { fi } +# internal function +# +# FUNCTION: update_depmod +# DESCRIPTION: +# It updates the modules.dep file for the current kernel. update_depmod() { debug-print-function ${FUNCNAME} $* @@ -195,6 +241,11 @@ update_depmod() { fi } +# internal function +# +# FUNCTION: update_modules +# DESCRIPTION: +# It calls the update-modules utility. update_modules() { debug-print-function ${FUNCNAME} $* @@ -211,6 +262,11 @@ update_modules() { fi } +# internal function +# +# FUNCTION: move_old_moduledb +# DESCRIPTION: +# It updates the location of the database used by the module-rebuild utility. move_old_moduledb() { debug-print-function ${FUNCNAME} $* @@ -226,6 +282,11 @@ move_old_moduledb() { fi } +# internal function +# +# FUNCTION: update_moduledb +# DESCRIPTION: +# It adds the package to the /var/lib/module-rebuild/moduledb database used by the module-rebuild utility. update_moduledb() { debug-print-function ${FUNCNAME} $* @@ -243,6 +304,12 @@ update_moduledb() { fi } +# internal function +# +# FUNCTION: remove_moduledb +# DESCRIPTION: +# It removes the package from the /var/lib/module-rebuild/moduledb database used by +# the module-rebuild utility. remove_moduledb() { debug-print-function ${FUNCNAME} $* @@ -255,6 +322,9 @@ remove_moduledb() { fi } +# @FUNCTION: set_kvobj +# @DESCRIPTION: +# It sets the KV_OBJ variable. set_kvobj() { debug-print-function ${FUNCNAME} $* @@ -289,12 +359,21 @@ get-KERNEL_CC() { echo "${kernel_cc}" } +# internal function +# +# FUNCTION: +# USAGE: /path/to/the/modulename_without_extension +# RETURN: A file in /etc/modules.d/ (kernel < 2.6) or /etc/modprobe.d/ (kernel >= 2.6) +# DESCRIPTION: +# This function will generate and install the neccessary modprobe.d/modules.d file from the +# information contained in the modules exported parms. +# (see the variables MODULESD__ENABLED, MODULESD__EXAMPLES, +# MODULESD__ALIASES, MODULESD__ADDITION and MODULESD__DOCS). +# +# At the end the documentation specified with MODULESD__DOCS is installed. generate_modulesd() { debug-print-function ${FUNCNAME} $* - # This function will generate the neccessary modules.d file from the - # information contained in the modules exported parms - local currm_path currm currm_t t myIFS myVAR local module_docs module_enabled module_aliases \ module_additions module_examples module_modinfo module_opts @@ -437,6 +516,13 @@ generate_modulesd() { return 0 } +# internal function +# +# FUNCTION: find_module_params +# USAGE: A string "NAME(LIBDIR:SRCDIR:OBJDIR)" +# RETURN: The string "modulename:NAME libdir:LIBDIR srcdir:SRCDIR objdir:OBJDIR" +# DESCRIPTION: +# Analyze the specification NAME(LIBDIR:SRCDIR:OBJDIR) of one module as described in MODULE_NAMES. find_module_params() { debug-print-function ${FUNCNAME} $* @@ -482,6 +568,11 @@ find_module_params() { # default ebuild functions # -------------------------------- +# @FUNCTION: linux-mod_pkg_setup +# @DESCRIPTION: +# It checks the CONFIG_CHECK options (see linux-info.eclass(5)), verifies that the kernel is +# configured, verifies that the sources are prepared, verifies that the modules support is builtin +# in the kernel and sets the object extension KV_OBJ. linux-mod_pkg_setup() { debug-print-function ${FUNCNAME} $* @@ -506,6 +597,14 @@ strip_modulenames() { done } +# @FUNCTION: linux-mod_src_compile +# @DESCRIPTION: +# It compiles all the modules specified in MODULE_NAMES. For each module the econf command is +# executed only if ECONF_PARAMS is defined, the name of the target is specified by BUILD_TARGETS +# while the options are in BUILD_PARAMS (all the modules share these variables). The compilation +# happens inside ${srcdir}. +# +# Look at the description of these variables for more details. linux-mod_src_compile() { debug-print-function ${FUNCNAME} $* @@ -558,6 +657,17 @@ linux-mod_src_compile() { ABI="${myABI}" } +# @FUNCTION: linux-mod_src_install +# @DESCRIPTION: +# It install the modules specified in MODULES_NAME. The modules should be inside the ${objdir} +# directory and they are installed inside /lib/modules/${KV_FULL}/${libdir}. +# +# The modprobe.d/modules.d configuration file is automatically generated if the +# MODULESD__* variables are defined. The only way to stop this process is by +# setting MODULESD__ENABLED=no. At the end the documentation specified via +# MODULESD__DOCS is also installed. +# +# Look at the description of these variables for more details. linux-mod_src_install() { debug-print-function ${FUNCNAME} $* @@ -585,6 +695,9 @@ linux-mod_src_install() { done } +# @FUNCTION: linux-mod_pkg_preinst +# @DESCRIPTION: +# It checks what to do after having merged the package. linux-mod_pkg_preinst() { debug-print-function ${FUNCNAME} $* @@ -593,6 +706,11 @@ linux-mod_pkg_preinst() { [ -d "${D}lib/modules" ] && UPDATE_MODULEDB=true || UPDATE_MODULEDB=false } +# @FUNCTION: linux-mod_pkg_postinst +# @DESCRIPTION: +# It executes /sbin/depmod and adds the package to the /var/lib/module-rebuild/moduledb +# database (if ${D}/lib/modules is created) and it runs /sbin/update-modules +# (if ${D}/etc/modules.d is created). linux-mod_pkg_postinst() { debug-print-function ${FUNCNAME} $* @@ -601,6 +719,10 @@ linux-mod_pkg_postinst() { ${UPDATE_MODULEDB} && update_moduledb; } +# @FUNCTION: linux-mod_pkg_postrm +# @DESCRIPTION: +# It removes the package from the /var/lib/module-rebuild/moduledb database but it doens't +# call /sbin/depmod and /sbin/update-modules because the modules are still installed. linux-mod_pkg_postrm() { debug-print-function ${FUNCNAME} $* remove_moduledb; -- cgit v1.2.3-65-gdbad