Operating SystemsLoadable Kernel Modules

Loadable Kernel Modules

LevelIntermediate

Duration75 mins

TopicLoadable Kernel Modules

4 / 5

Module Management

Mastering the Module Lifecycle

Kernel modules are not merely loaded and forgotten—they have a complete lifecycle that system administrators and developers must understand and manage. From initial loading with proper dependencies, through runtime configuration, to controlled unloading, each phase requires specific tools and techniques.

Effective module management goes beyond basic insmod and rmmod commands. It encompasses dependency resolution, automatic loading through udev, parameter configuration, blacklisting, debugging load failures, and maintaining modules across kernel updates. Mastery of these skills is essential for anyone working with Linux at a system level.

This page provides comprehensive coverage of the module management toolchain and the underlying kernel mechanisms that make it work.

What You Will Learn

By the end of this page, you will master the complete module management toolkit: insmod, rmmod, modprobe, lsmod, and modinfo. You'll understand dependency resolution, automatic module loading, configuration files, parameter handling, and techniques for debugging module loading failures.

The Module Loading Commands

Linux provides two primary commands for loading kernel modules: insmod and modprobe. Understanding their differences is crucial for effective module management.

insmod — Insert Module:

insmod is the low-level module loading tool. It takes an explicit path to a .ko file and attempts to load it directly:

$ sudo insmod /path/to/mymodule.ko

Characteristics of insmod:

Requires exact file path to the .ko file
Does not resolve dependencies
No automatic parameter handling from config files
Minimal intelligence—performs exactly what you specify
Useful for development and debugging

modprobe — Module Probe:

modprobe is the intelligent module loading tool. It uses module name (not path) and handles dependencies automatically:

$ sudo modprobe e1000e

insmod vs modprobe Comparison
Feature	insmod	modprobe
Input	Full path to .ko file	Module name only
Dependencies	Manual (fails if missing)	Automatic resolution
Configuration	Parameters on command line only	Reads /etc/modprobe.d/
Module path	Specified explicitly	Searches /lib/modules/$(uname -r)/
Aliases	Not supported	Resolves device aliases
Blacklisting	Ignores blacklist	Honors blacklist
Use case	Development, single modules	Production, system administration

loading_examples.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# insmod examples
$ sudo insmod ./mydriver.ko                    # Load from current directory
$ sudo insmod /lib/modules/5.15.0/extra/mydriver.ko
$ sudo insmod mydriver.ko debug=1 max_devices=4  # With parameters
 
# Failure without dependencies:
$ sudo insmod ./usb_storage.ko
insmod: ERROR: could not insert module: Unknown symbol in module
 
# modprobe examples
$ sudo modprobe e1000e              # Load by name, deps handled
$ sudo modprobe -v e1000e           # Verbose: show what's loaded
insmod /lib/modules/5.15.0/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
 
# modprobe with parameters
$ sudo modprobe bonding mode=active-backup primary=eth0
 
# See what would be loaded without actually loading
$ modprobe -n -v snd_hda_intel
insmod /lib/modules/5.15.0/kernel/sound/core/snd.ko
insmod /lib/modules/5.15.0/kernel/sound/core/snd-timer.ko
insmod /lib/modules/5.15.0/kernel/sound/core/snd-pcm.ko
insmod /lib/modules/5.15.0/kernel/sound/pci/hda/snd-hda-core.ko
insmod /lib/modules/5.15.0/kernel/sound/pci/hda/snd-hda-intel.ko

Development Workflow

During development, use insmod with the explicit path to your compiled module. For production and installed modules, always use modprobe—it ensures dependencies are satisfied and configuration is applied correctly.

Dependency Resolution

Modules often depend on symbols exported by other modules. The kernel cannot load a module with unresolved symbols, so dependencies must be loaded first. modprobe automates this through the modules.dep file.

modules.dep and depmod:

The depmod command scans all modules and generates dependency information:

$ sudo depmod -a    # Regenerate for current kernel
$ sudo depmod -a 5.15.0   # Regenerate for specific kernel

depmod produces /lib/modules/$(uname -r)/modules.dep:

# Example modules.dep entries
kernel/drivers/usb/storage/usb-storage.ko: kernel/drivers/scsi/scsi_mod.ko
kernel/sound/pci/hda/snd-hda-intel.ko: kernel/sound/pci/hda/snd-hda-codec.ko kernel/sound/pci/hda/snd-hda-core.ko kernel/sound/core/snd-pcm.ko kernel/sound/core/snd.ko

Format: module.ko: dependency1.ko dependency2.ko ...

dependency_exploration.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# View dependencies for a specific module
$ modinfo --field depends usb-storage
scsi_mod,usb-common
 
# Show full dependency tree
$ modprobe --show-depends usb-storage
insmod /lib/modules/5.15.0/kernel/drivers/scsi/scsi_mod.ko
insmod /lib/modules/5.15.0/kernel/drivers/usb/common/usb-common.ko
insmod /lib/modules/5.15.0/kernel/drivers/usb/storage/usb-storage.ko
 
# Reverse dependency: what uses this module?
$ lsmod | grep scsi_mod
scsi_mod              253952  5 usb_storage,sd_mod,sr_mod,sg,libata
 
# modules.dep.bin for fast binary lookup
$ ls -la /lib/modules/$(uname -r)/modules.dep*
-rw-r--r-- 1 root root 523264 Dec 15 10:00 modules.dep
-rw-r--r-- 1 root root 365876 Dec 15 10:00 modules.dep.bin
 
# Rebuild after installing new modules
$ sudo depmod -a
$ sudo depmod -A  # Only check for changes (faster)

Soft dependencies:

Some module relationships are optional—"nice to have" rather than required. These are soft dependencies declared in module metadata:

MODULE_SOFTDEP("pre: i2c_algo_bit");
MODULE_SOFTDEP("post: drm_kms_helper");

pre: modules that should be loaded before this one (if available)
post: modules that should be loaded after this one (if needed)

modprobe attempts to satisfy soft dependencies but doesn't fail if they're unavailable.

Circular Dependencies

Circular dependencies (A requires B, B requires A) are forbidden and indicate a design flaw. The module system cannot resolve such cycles. If you encounter circular dependency errors, the module design needs refactoring or the dependency graph needs review.

Unloading Modules

Removing modules from the running kernel is handled by rmmod and modprobe -r. However, unloading is more complex than loading—the kernel must verify that removal is safe.

Basic unloading:

$ sudo rmmod mymodule       # Low-level removal
$ sudo modprobe -r mymodule # With dependency handling

Reference counting:

Modules maintain a use count tracking how many kernel subsystems and other modules are using them. Unloading is only permitted when the count reaches zero:

unloading_examples.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# View module reference counts
$ lsmod
Module                  Size  Used by
nvidia_drm             69632  3      # Used by 3 references
nvidia_modeset       1236992  2 nvidia_drm
nvidia              39313408  64 nvidia_modeset
snd_hda_intel          57344  0      # Not in use, can unload
 
# Attempt to unload in-use module (fails)
$ sudo rmmod nvidia
rmmod: ERROR: Module nvidia is in use by: nvidia_modeset
 
# Must unload dependents first
$ sudo rmmod nvidia_drm
$ sudo rmmod nvidia_modeset
$ sudo rmmod nvidia
 
# modprobe -r attempts to unload dependencies recursively
$ sudo modprobe -r nvidia_drm
#  Attempts: nvidia_drm → nvidia_modeset → nvidia
 
# Force removal (DANGEROUS - can crash system)
$ sudo rmmod -f nvidia
# Only works if kernel compiled with CONFIG_MODULE_FORCE_UNLOAD
 
# Why a module might be "in use":
# - Open file handles (/dev entries)
# - Mounted filesystems (fs modules)
# - Active network interfaces (net drivers)
# - Referenced by other modules
# - Kernel threads running module code

Common unloading complications:

Why Modules Refuse to Unload

•Open device files — Close all programs using /dev entries provided by the module.
•Mounted filesystems — Unmount any filesystems using the module (e.g., ext4, btrfs).
•Active network interfaces — Bring down interfaces before removing their driver.
•Dependent modules — Other modules using this one must be unloaded first.
•Kernel threads — Some modules create threads that must be stopped.
•Hardware busy — DMA transfers or pending operations must complete.

Module Cleanup

Well-designed modules clean up completely: free memory, unregister devices, stop threads, and release hardware. The module's exit() function handles this. Poorly designed modules may leak resources or refuse to unload gracefully.

Configuration Files

Module behavior is configured through files in /etc/modprobe.d/. These configuration files affect how modprobe handles module loading, including parameters, aliases, and blacklisting.

Configuration file format:

Files in /etc/modprobe.d/ contain directives in a simple line-based format. Files must end in .conf to be processed.

$ ls /etc/modprobe.d/
alsa-base.conf
blacklist.conf
bonding.conf
intel-microcode.conf
iwlwifi.conf
nvidia.conf

modprobe.d/examples.conf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# ======================================
# Module Parameters (options directive)
# ======================================
 
# Set default parameters for a module
options bonding mode=1 miimon=100 max_bonds=2
 
# Intel WiFi power management
options iwlwifi power_save=0 11n_disable=1
 
# NVIDIA settings
options nvidia NVreg_PreserveVideoMemoryAllocations=1
 
# ======================================
# Module Aliases (alias directive)  
# ======================================
 
# Create an alias for a module
alias eth0 e1000e
alias wlan0 iwlwifi
 
# Hardware aliases (auto-generated by modules.alias)
alias pci:v00008086d00001539sv*sd*bc02sc00i* igb
 
# ======================================
# Blacklisting (blacklist directive)
# ======================================
 
# Prevent module from loading automatically
blacklist nouveau
blacklist pcspkr
 
# Note: blacklist doesn't prevent manual loading
# Use 'install' directive for complete blocking
 
# ======================================
# Install/Remove Hooks (install/remove)
# ======================================
 
# Run command instead of loading module
install pcspkr /bin/false
 
# Run custom script before loading
install mymodule /sbin/prepare-hardware && /sbin/modprobe --ignore-install mymodule
 
# Run command before unloading
remove mymodule /sbin/cleanup-hardware; /sbin/modprobe -r --ignore-remove mymodule
 
# ======================================
# Soft Dependencies (softdep directive)
# ======================================
 
# Specify soft dependency relationships
softdep iwlwifi pre: cfg80211
softdep snd-hda-intel post: snd-hda-codec-realtek

modprobe.d Directive Reference
Directive	Syntax	Purpose
options	options <module> <params>	Set default module parameters
alias	alias <name> <module>	Create alternative module names
blacklist	blacklist <module>	Prevent auto-loading by udev
install	install <module> <command>	Run command when loading module
remove	remove <module> <command>	Run command when removing module
softdep	softdep <module> pre: <deps> post: <deps>	Optional dependencies

Debugging Configuration

Use 'modprobe -c' to dump the effective configuration from all files. Use 'modprobe -c | grep <module>' to see settings for a specific module. This helps debug when configuration isn't working as expected.

Automatic Module Loading

Modern Linux systems load most modules automatically without administrator intervention. This plug-and-play functionality relies on cooperation between the kernel, udev, and the module alias system.

The device detection flow:

1. Hardware detected (boot, hotplug, scan)
           ↓
2. Kernel creates device in /sys
           ↓
3. Kernel sends uevent to userspace
           ↓
4. udev receives event
           ↓
5. udev reads device attributes (vendor, product, class)
           ↓
6. udev constructs modalias string
           ↓
7. udev calls modprobe with alias
           ↓
8. modprobe searches modules.alias for matching module
           ↓
9. Module loaded, driver binds to device

automatic_loading.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# View aliases defined by a module
$ modinfo e1000e | grep ^alias:
alias:          pci:v00008086d000015F3sv*sd*bc*sc*i*
alias:          pci:v00008086d000015F2sv*sd*bc*sc*i*
alias:          pci:v00008086d00001570sv*sd*bc*sc*i*
...
 
# View modalias for a device
$ cat /sys/class/net/enp0s31f6/device/modalias
pci:v00008086d000015D6sv00001028sd000007A1bc02sc00i00
 
# Test which module would be loaded for an alias
$ modprobe --resolve-alias 'pci:v00008086d000015D6sv*sd*bc02sc00i*'
e1000e
 
# View the modules.alias file
$ grep -m 3 e1000e /lib/modules/$(uname -r)/modules.alias
alias pci:v00008086d000015F3sv*sd*bc*sc*i* e1000e
alias pci:v00008086d000015F2sv*sd*bc*sc*i* e1000e
alias pci:v00008086d00001570sv*sd*bc*sc*i* e1000e
 
# Monitor module loading in real-time
$ udevadm monitor --property &
$ # (plug in USB device, watch output)
 
# Manually trigger uevents (rescans devices)
$ echo 1 > /sys/bus/pci/rescan
$ udevadm trigger

Module alias patterns:

Aliases use wildcard patterns to match device identifiers:

pci:vVVVVVVVVdDDDDDDDDsvSSSSSSSSsdssssssssbc**sc**i**
    ↓       ↓         ↓         ↓         ↓  ↓  ↓
   vendor  device    subvendor  subdevice class subclass interface

v prefix = vendor ID
d prefix = device ID
sv = subsystem vendor
sd = subsystem device
bc = base class
sc = subclass
* = wildcard

This allows drivers to match broad categories (e.g., "all Intel network controllers") or specific devices.

Boot-Time Loading

Critical boot modules are loaded from initramfs before the root filesystem is available. The 'dracut' or 'mkinitrd' tools include necessary modules in initramfs based on detected hardware. After boot, udev triggers loading of remaining modules for hotplugged and secondary devices.

Module Information Commands

Several commands provide information about loaded modules and module files. These tools are essential for system administration and debugging.

lsmod — List Modules:

Displays currently loaded modules:

$ lsmod
Module                  Size  Used by
e1000e                294912  0
nvidia_drm             69632  3
snd_hda_intel          57344  4

Module: Name of the loaded module
Size: Memory usage in bytes
Used by: Reference count and dependent modules

info_commands.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# lsmod - list loaded modules
$ lsmod | head -5
Module                  Size  Used by
rfkill                 28672  2 bluetooth,cfg80211
bluetooth             720896  5 btrtl,btintel,btbcm,bnep,btusb
cfg80211              974848  3 iwlmvm,iwlwifi,mac80211
 
# modinfo - detailed module information
$ modinfo e1000e
filename:       /lib/modules/5.15.0/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
license:        GPL
description:    Intel(R) PRO/1000 Network Driver
author:         Intel Corporation, <linux.nics@intel.com>
srcversion:     1A2B3C4D5E6F7890
alias:          pci:v00008086d00001539sv*sd*bc*sc*i*
depends:        
retpoline:      Y
intree:         Y
vermagic:       5.15.0-generic SMP mod_unload
parm:           debug:Debug level (0=none,...,16=all)
parm:           copybreak:Copy breakpoint for copy-only-tiny-frames
parm:           TxIntDelay:Tx interrupt delay
 
# Get specific field from modinfo
$ modinfo -F vermagic e1000e
5.15.0-generic SMP mod_unload
 
$ modinfo -F parm e1000e | head -3
debug:Debug level (0=none,...,16=all)
copybreak:Copy breakpoint for copy-only-tiny-frames
TxIntDelay:Tx interrupt delay
 
# /proc/modules - raw kernel module info
$ cat /proc/modules | grep e1000e
e1000e 294912 0 - Live 0xffffffxxxxxxxxxx
 
# /sys/module - per-module sysfs entries
$ ls /sys/module/e1000e/
coresize  holders  initsize  initstate  notes  parameters  refcnt  srcversion  taint  uevent
 
$ cat /sys/module/e1000e/parameters/debug
0

Module Information Sources
Source	Type	Information Provided
lsmod	Command	Loaded modules, sizes, dependencies
modinfo	Command	Detailed metadata from .ko file
/proc/modules	Proc file	Raw module list with addresses
/sys/module/<name>/	Sysfs dir	Per-module parameters and state
/sys/module/<name>/parameters/	Sysfs dir	Current parameter values
/lib/modules/$(uname -r)/	Directory	Available module files

Parameter Exploration

To see all parameters a module accepts with descriptions: 'modinfo -p <module>'. To see current values of parameters for a loaded module: 'cat /sys/module/<name>/parameters/*'. Some parameters can be changed at runtime by writing to these files.

Troubleshooting Module Loading

Module loading can fail for various reasons. Systematic debugging helps identify and resolve the root cause.

Common error messages and causes:

Module Loading Error Reference
Error Message	Likely Cause	Resolution
Unknown symbol in module	Missing dependency or wrong kernel version	Check dependencies; rebuild for correct kernel
Invalid module format	Compiled for different kernel; corrupt file	Rebuild module for target kernel
Module version magic mismatch	Kernel/module version mismatch	Match kernel versions; use DKMS
Required key not available	Module signature invalid or missing	Sign module or disable signature enforcement
Operation not permitted	Secure Boot, blacklist, or SELinux/AppArmor	Check security policies and blacklists
Resource busy	Device/resource already claimed	Unload conflicting module first
No such file or directory	Module file not found	Run depmod; check module path

troubleshooting.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# Step 1: Check kernel messages for detailed errors
$ dmesg | tail -20
[12345.678] mymodule: Unknown symbol kmalloc_caches (err 0)
[12345.679] mymodule: Unknown symbol __kmalloc (err 0)
 
# Step 2: Verify module is for correct kernel
$ modinfo mymodule.ko | grep vermagic
vermagic:       5.10.0-generic SMP mod_unload
$ uname -r
5.15.0-generic  # Mismatch!
 
# Step 3: Check symbol availability
$ grep kmalloc /lib/modules/$(uname -r)/build/Module.symvers
0x12345678  kmalloc  vmlinux  EXPORT_SYMBOL
 
# Step 4: Verify dependencies exist
$ modprobe --show-depends mymodule
modprobe: FATAL: Module mymodule not found.
$ ls /lib/modules/$(uname -r)/extra/mymodule.ko
ls: cannot access: No such file or directory
 
# Step 5: Regenerate module database
$ sudo depmod -a
 
# Step 6: Check for blacklisting
$ grep mymodule /etc/modprobe.d/*.conf
/etc/modprobe.d/blacklist.conf:blacklist mymodule
 
# Step 7: Check Secure Boot status
$ mokutil --sb-state
SecureBoot enabled
 
# Step 8: Debug with verbose modprobe
$ sudo modprobe -v --first-time mymodule
insmod /lib/modules/5.15.0/extra/mymodule.ko
modprobe: ERROR: could not insert 'mymodule': Invalid argument
 
# Step 9: Try with strace for system call errors
$ sudo strace modprobe mymodule 2>&1 | grep -E '(open|init_module)'

Tainting the Kernel

Loading certain modules 'taints' the kernel, affecting support and bug reports. Check /proc/sys/kernel/tainted for taint status. Common taints: proprietary module (P), forced load (F), staging driver (C). Tainting doesn't prevent loading but may affect vendor support.

Summary: Module Management Mastery

Effective module management is a cornerstone skill for Linux system administrators and kernel developers. We've covered the complete toolkit:

Key Takeaways

•Two loading tools serve different purposes: insmod for development (explicit path, no dependencies), modprobe for production (automatic dependencies, configuration).
•Dependency resolution is automated through modules.dep, generated by depmod. Dependencies must be loaded in correct order; modprobe handles this automatically.
•Unloading requires reference count to reach zero—modules in use by other modules or with open device handles cannot be removed without force (dangerous).
•Configuration files in /etc/modprobe.d/ control parameters, aliases, blacklists, and install hooks. These apply to modprobe operations.
•Automatic loading via udev uses module aliases matching device attributes, enabling plug-and-play functionality for hardware.
•Information tools (lsmod, modinfo, /sys/module) provide visibility into loaded modules, parameters, and dependencies.
•Troubleshooting follows systematic steps: check dmesg, verify versions, confirm dependencies, check blacklists, and examine security policies.

What's next:

The power of kernel modules comes with significant security implications. The next page examines the security aspects of loadable modules—from malicious kernel code injection to module signing, mandatory access controls, and best practices for secure module management.

Page Complete

You now have comprehensive knowledge of module management—loading, unloading, configuration, automatic handling, and troubleshooting. These skills are essential for effective Linux system administration.

4 / 5

Loading learning content...

Operating SystemsLoadable Kernel Modules

Loadable Kernel Modules

LevelIntermediate

Duration75 mins

TopicLoadable Kernel Modules

4 / 5

Module Management

Mastering the Module Lifecycle

This page provides comprehensive coverage of the module management toolchain and the underlying kernel mechanisms that make it work.

What You Will Learn

The Module Loading Commands

Linux provides two primary commands for loading kernel modules: insmod and modprobe. Understanding their differences is crucial for effective module management.

insmod — Insert Module:

insmod is the low-level module loading tool. It takes an explicit path to a .ko file and attempts to load it directly:

$ sudo insmod /path/to/mymodule.ko

Characteristics of insmod:

Requires exact file path to the .ko file
Does not resolve dependencies
No automatic parameter handling from config files
Minimal intelligence—performs exactly what you specify
Useful for development and debugging

modprobe — Module Probe:

modprobe is the intelligent module loading tool. It uses module name (not path) and handles dependencies automatically:

$ sudo modprobe e1000e

insmod vs modprobe Comparison
Feature	insmod	modprobe
Input	Full path to .ko file	Module name only
Dependencies	Manual (fails if missing)	Automatic resolution
Configuration	Parameters on command line only	Reads /etc/modprobe.d/
Module path	Specified explicitly	Searches /lib/modules/$(uname -r)/
Aliases	Not supported	Resolves device aliases
Blacklisting	Ignores blacklist	Honors blacklist
Use case	Development, single modules	Production, system administration

loading_examples.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# insmod examples
$ sudo insmod ./mydriver.ko                    # Load from current directory
$ sudo insmod /lib/modules/5.15.0/extra/mydriver.ko
$ sudo insmod mydriver.ko debug=1 max_devices=4  # With parameters
 
# Failure without dependencies:
$ sudo insmod ./usb_storage.ko
insmod: ERROR: could not insert module: Unknown symbol in module
 
# modprobe examples
$ sudo modprobe e1000e              # Load by name, deps handled
$ sudo modprobe -v e1000e           # Verbose: show what's loaded
insmod /lib/modules/5.15.0/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
 
# modprobe with parameters
$ sudo modprobe bonding mode=active-backup primary=eth0
 
# See what would be loaded without actually loading
$ modprobe -n -v snd_hda_intel
insmod /lib/modules/5.15.0/kernel/sound/core/snd.ko
insmod /lib/modules/5.15.0/kernel/sound/core/snd-timer.ko
insmod /lib/modules/5.15.0/kernel/sound/core/snd-pcm.ko
insmod /lib/modules/5.15.0/kernel/sound/pci/hda/snd-hda-core.ko
insmod /lib/modules/5.15.0/kernel/sound/pci/hda/snd-hda-intel.ko

Development Workflow

Dependency Resolution

modules.dep and depmod:

The depmod command scans all modules and generates dependency information:

$ sudo depmod -a    # Regenerate for current kernel
$ sudo depmod -a 5.15.0   # Regenerate for specific kernel

depmod produces /lib/modules/$(uname -r)/modules.dep:

# Example modules.dep entries
kernel/drivers/usb/storage/usb-storage.ko: kernel/drivers/scsi/scsi_mod.ko
kernel/sound/pci/hda/snd-hda-intel.ko: kernel/sound/pci/hda/snd-hda-codec.ko kernel/sound/pci/hda/snd-hda-core.ko kernel/sound/core/snd-pcm.ko kernel/sound/core/snd.ko

Format: module.ko: dependency1.ko dependency2.ko ...

dependency_exploration.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# View dependencies for a specific module
$ modinfo --field depends usb-storage
scsi_mod,usb-common
 
# Show full dependency tree
$ modprobe --show-depends usb-storage
insmod /lib/modules/5.15.0/kernel/drivers/scsi/scsi_mod.ko
insmod /lib/modules/5.15.0/kernel/drivers/usb/common/usb-common.ko
insmod /lib/modules/5.15.0/kernel/drivers/usb/storage/usb-storage.ko
 
# Reverse dependency: what uses this module?
$ lsmod | grep scsi_mod
scsi_mod              253952  5 usb_storage,sd_mod,sr_mod,sg,libata
 
# modules.dep.bin for fast binary lookup
$ ls -la /lib/modules/$(uname -r)/modules.dep*
-rw-r--r-- 1 root root 523264 Dec 15 10:00 modules.dep
-rw-r--r-- 1 root root 365876 Dec 15 10:00 modules.dep.bin
 
# Rebuild after installing new modules
$ sudo depmod -a
$ sudo depmod -A  # Only check for changes (faster)

Soft dependencies:

Some module relationships are optional—"nice to have" rather than required. These are soft dependencies declared in module metadata:

MODULE_SOFTDEP("pre: i2c_algo_bit");
MODULE_SOFTDEP("post: drm_kms_helper");

pre: modules that should be loaded before this one (if available)
post: modules that should be loaded after this one (if needed)

modprobe attempts to satisfy soft dependencies but doesn't fail if they're unavailable.

Circular Dependencies

Unloading Modules

Removing modules from the running kernel is handled by rmmod and modprobe -r. However, unloading is more complex than loading—the kernel must verify that removal is safe.

Basic unloading:

$ sudo rmmod mymodule       # Low-level removal
$ sudo modprobe -r mymodule # With dependency handling

Reference counting:

Modules maintain a use count tracking how many kernel subsystems and other modules are using them. Unloading is only permitted when the count reaches zero:

unloading_examples.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# View module reference counts
$ lsmod
Module                  Size  Used by
nvidia_drm             69632  3      # Used by 3 references
nvidia_modeset       1236992  2 nvidia_drm
nvidia              39313408  64 nvidia_modeset
snd_hda_intel          57344  0      # Not in use, can unload
 
# Attempt to unload in-use module (fails)
$ sudo rmmod nvidia
rmmod: ERROR: Module nvidia is in use by: nvidia_modeset
 
# Must unload dependents first
$ sudo rmmod nvidia_drm
$ sudo rmmod nvidia_modeset
$ sudo rmmod nvidia
 
# modprobe -r attempts to unload dependencies recursively
$ sudo modprobe -r nvidia_drm
#  Attempts: nvidia_drm → nvidia_modeset → nvidia
 
# Force removal (DANGEROUS - can crash system)
$ sudo rmmod -f nvidia
# Only works if kernel compiled with CONFIG_MODULE_FORCE_UNLOAD
 
# Why a module might be "in use":
# - Open file handles (/dev entries)
# - Mounted filesystems (fs modules)
# - Active network interfaces (net drivers)
# - Referenced by other modules
# - Kernel threads running module code

Common unloading complications:

Why Modules Refuse to Unload

•Open device files — Close all programs using /dev entries provided by the module.
•Mounted filesystems — Unmount any filesystems using the module (e.g., ext4, btrfs).
•Active network interfaces — Bring down interfaces before removing their driver.
•Dependent modules — Other modules using this one must be unloaded first.
•Kernel threads — Some modules create threads that must be stopped.
•Hardware busy — DMA transfers or pending operations must complete.

Module Cleanup

Configuration Files

Module behavior is configured through files in /etc/modprobe.d/. These configuration files affect how modprobe handles module loading, including parameters, aliases, and blacklisting.

Configuration file format:

Files in /etc/modprobe.d/ contain directives in a simple line-based format. Files must end in .conf to be processed.

$ ls /etc/modprobe.d/
alsa-base.conf
blacklist.conf
bonding.conf
intel-microcode.conf
iwlwifi.conf
nvidia.conf

modprobe.d/examples.conf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# ======================================
# Module Parameters (options directive)
# ======================================
 
# Set default parameters for a module
options bonding mode=1 miimon=100 max_bonds=2
 
# Intel WiFi power management
options iwlwifi power_save=0 11n_disable=1
 
# NVIDIA settings
options nvidia NVreg_PreserveVideoMemoryAllocations=1
 
# ======================================
# Module Aliases (alias directive)  
# ======================================
 
# Create an alias for a module
alias eth0 e1000e
alias wlan0 iwlwifi
 
# Hardware aliases (auto-generated by modules.alias)
alias pci:v00008086d00001539sv*sd*bc02sc00i* igb
 
# ======================================
# Blacklisting (blacklist directive)
# ======================================
 
# Prevent module from loading automatically
blacklist nouveau
blacklist pcspkr
 
# Note: blacklist doesn't prevent manual loading
# Use 'install' directive for complete blocking
 
# ======================================
# Install/Remove Hooks (install/remove)
# ======================================
 
# Run command instead of loading module
install pcspkr /bin/false
 
# Run custom script before loading
install mymodule /sbin/prepare-hardware && /sbin/modprobe --ignore-install mymodule
 
# Run command before unloading
remove mymodule /sbin/cleanup-hardware; /sbin/modprobe -r --ignore-remove mymodule
 
# ======================================
# Soft Dependencies (softdep directive)
# ======================================
 
# Specify soft dependency relationships
softdep iwlwifi pre: cfg80211
softdep snd-hda-intel post: snd-hda-codec-realtek

modprobe.d Directive Reference
Directive	Syntax	Purpose
options	options <module> <params>	Set default module parameters
alias	alias <name> <module>	Create alternative module names
blacklist	blacklist <module>	Prevent auto-loading by udev
install	install <module> <command>	Run command when loading module
remove	remove <module> <command>	Run command when removing module
softdep	softdep <module> pre: <deps> post: <deps>	Optional dependencies

Debugging Configuration

Automatic Module Loading

The device detection flow:

1. Hardware detected (boot, hotplug, scan)
           ↓
2. Kernel creates device in /sys
           ↓
3. Kernel sends uevent to userspace
           ↓
4. udev receives event
           ↓
5. udev reads device attributes (vendor, product, class)
           ↓
6. udev constructs modalias string
           ↓
7. udev calls modprobe with alias
           ↓
8. modprobe searches modules.alias for matching module
           ↓
9. Module loaded, driver binds to device

automatic_loading.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# View aliases defined by a module
$ modinfo e1000e | grep ^alias:
alias:          pci:v00008086d000015F3sv*sd*bc*sc*i*
alias:          pci:v00008086d000015F2sv*sd*bc*sc*i*
alias:          pci:v00008086d00001570sv*sd*bc*sc*i*
...
 
# View modalias for a device
$ cat /sys/class/net/enp0s31f6/device/modalias
pci:v00008086d000015D6sv00001028sd000007A1bc02sc00i00
 
# Test which module would be loaded for an alias
$ modprobe --resolve-alias 'pci:v00008086d000015D6sv*sd*bc02sc00i*'
e1000e
 
# View the modules.alias file
$ grep -m 3 e1000e /lib/modules/$(uname -r)/modules.alias
alias pci:v00008086d000015F3sv*sd*bc*sc*i* e1000e
alias pci:v00008086d000015F2sv*sd*bc*sc*i* e1000e
alias pci:v00008086d00001570sv*sd*bc*sc*i* e1000e
 
# Monitor module loading in real-time
$ udevadm monitor --property &
$ # (plug in USB device, watch output)
 
# Manually trigger uevents (rescans devices)
$ echo 1 > /sys/bus/pci/rescan
$ udevadm trigger

Module alias patterns:

Aliases use wildcard patterns to match device identifiers:

pci:vVVVVVVVVdDDDDDDDDsvSSSSSSSSsdssssssssbc**sc**i**
    ↓       ↓         ↓         ↓         ↓  ↓  ↓
   vendor  device    subvendor  subdevice class subclass interface

v prefix = vendor ID
d prefix = device ID
sv = subsystem vendor
sd = subsystem device
bc = base class
sc = subclass
* = wildcard

This allows drivers to match broad categories (e.g., "all Intel network controllers") or specific devices.

Boot-Time Loading

Module Information Commands

Several commands provide information about loaded modules and module files. These tools are essential for system administration and debugging.

lsmod — List Modules:

Displays currently loaded modules:

$ lsmod
Module                  Size  Used by
e1000e                294912  0
nvidia_drm             69632  3
snd_hda_intel          57344  4

Module: Name of the loaded module
Size: Memory usage in bytes
Used by: Reference count and dependent modules

info_commands.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# lsmod - list loaded modules
$ lsmod | head -5
Module                  Size  Used by
rfkill                 28672  2 bluetooth,cfg80211
bluetooth             720896  5 btrtl,btintel,btbcm,bnep,btusb
cfg80211              974848  3 iwlmvm,iwlwifi,mac80211
 
# modinfo - detailed module information
$ modinfo e1000e
filename:       /lib/modules/5.15.0/kernel/drivers/net/ethernet/intel/e1000e/e1000e.ko
license:        GPL
description:    Intel(R) PRO/1000 Network Driver
author:         Intel Corporation, <linux.nics@intel.com>
srcversion:     1A2B3C4D5E6F7890
alias:          pci:v00008086d00001539sv*sd*bc*sc*i*
depends:        
retpoline:      Y
intree:         Y
vermagic:       5.15.0-generic SMP mod_unload
parm:           debug:Debug level (0=none,...,16=all)
parm:           copybreak:Copy breakpoint for copy-only-tiny-frames
parm:           TxIntDelay:Tx interrupt delay
 
# Get specific field from modinfo
$ modinfo -F vermagic e1000e
5.15.0-generic SMP mod_unload
 
$ modinfo -F parm e1000e | head -3
debug:Debug level (0=none,...,16=all)
copybreak:Copy breakpoint for copy-only-tiny-frames
TxIntDelay:Tx interrupt delay
 
# /proc/modules - raw kernel module info
$ cat /proc/modules | grep e1000e
e1000e 294912 0 - Live 0xffffffxxxxxxxxxx
 
# /sys/module - per-module sysfs entries
$ ls /sys/module/e1000e/
coresize  holders  initsize  initstate  notes  parameters  refcnt  srcversion  taint  uevent
 
$ cat /sys/module/e1000e/parameters/debug
0

Module Information Sources
Source	Type	Information Provided
lsmod	Command	Loaded modules, sizes, dependencies
modinfo	Command	Detailed metadata from .ko file
/proc/modules	Proc file	Raw module list with addresses
/sys/module/<name>/	Sysfs dir	Per-module parameters and state
/sys/module/<name>/parameters/	Sysfs dir	Current parameter values
/lib/modules/$(uname -r)/	Directory	Available module files

Parameter Exploration

Troubleshooting Module Loading

Module loading can fail for various reasons. Systematic debugging helps identify and resolve the root cause.

Common error messages and causes:

Module Loading Error Reference
Error Message	Likely Cause	Resolution
Unknown symbol in module	Missing dependency or wrong kernel version	Check dependencies; rebuild for correct kernel
Invalid module format	Compiled for different kernel; corrupt file	Rebuild module for target kernel
Module version magic mismatch	Kernel/module version mismatch	Match kernel versions; use DKMS
Required key not available	Module signature invalid or missing	Sign module or disable signature enforcement
Operation not permitted	Secure Boot, blacklist, or SELinux/AppArmor	Check security policies and blacklists
Resource busy	Device/resource already claimed	Unload conflicting module first
No such file or directory	Module file not found	Run depmod; check module path

troubleshooting.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# Step 1: Check kernel messages for detailed errors
$ dmesg | tail -20
[12345.678] mymodule: Unknown symbol kmalloc_caches (err 0)
[12345.679] mymodule: Unknown symbol __kmalloc (err 0)
 
# Step 2: Verify module is for correct kernel
$ modinfo mymodule.ko | grep vermagic
vermagic:       5.10.0-generic SMP mod_unload
$ uname -r
5.15.0-generic  # Mismatch!
 
# Step 3: Check symbol availability
$ grep kmalloc /lib/modules/$(uname -r)/build/Module.symvers
0x12345678  kmalloc  vmlinux  EXPORT_SYMBOL
 
# Step 4: Verify dependencies exist
$ modprobe --show-depends mymodule
modprobe: FATAL: Module mymodule not found.
$ ls /lib/modules/$(uname -r)/extra/mymodule.ko
ls: cannot access: No such file or directory
 
# Step 5: Regenerate module database
$ sudo depmod -a
 
# Step 6: Check for blacklisting
$ grep mymodule /etc/modprobe.d/*.conf
/etc/modprobe.d/blacklist.conf:blacklist mymodule
 
# Step 7: Check Secure Boot status
$ mokutil --sb-state
SecureBoot enabled
 
# Step 8: Debug with verbose modprobe
$ sudo modprobe -v --first-time mymodule
insmod /lib/modules/5.15.0/extra/mymodule.ko
modprobe: ERROR: could not insert 'mymodule': Invalid argument
 
# Step 9: Try with strace for system call errors
$ sudo strace modprobe mymodule 2>&1 | grep -E '(open|init_module)'

Tainting the Kernel

Summary: Module Management Mastery

Effective module management is a cornerstone skill for Linux system administrators and kernel developers. We've covered the complete toolkit:

Key Takeaways

•Two loading tools serve different purposes: insmod for development (explicit path, no dependencies), modprobe for production (automatic dependencies, configuration).
•Dependency resolution is automated through modules.dep, generated by depmod. Dependencies must be loaded in correct order; modprobe handles this automatically.
•Unloading requires reference count to reach zero—modules in use by other modules or with open device handles cannot be removed without force (dangerous).
•Configuration files in /etc/modprobe.d/ control parameters, aliases, blacklists, and install hooks. These apply to modprobe operations.
•Automatic loading via udev uses module aliases matching device attributes, enabling plug-and-play functionality for hardware.
•Information tools (lsmod, modinfo, /sys/module) provide visibility into loaded modules, parameters, and dependencies.
•Troubleshooting follows systematic steps: check dmesg, verify versions, confirm dependencies, check blacklists, and examine security policies.

What's next:

Page Complete

4 / 5