Module Reference Counting — How the Kernel Tracks “In Use”

Every loaded kernel module has an internal reference count. This count tells the kernel how many things are currently using that module. The kernel will not allow a module to be unloaded as long as its reference count is greater than zero.

The reference count you see in lsmod is not just about other modules. It can be incremented by:

• Another module depending on and using this module’s exported symbols
• A process that has opened a device file backed by this module
• A subsystem that holds an internal reference (e.g. a registered driver entry)

The two kernel functions that manage the reference count are try_module_get() and module_put(). These are defined in include/linux/module.h.

/* Increment the reference count of a module.
 * Returns true (non-zero) on success.
 * Returns false (zero) if the module is being unloaded — do not use it.
 */
bool try_module_get(struct module *module);

/* Decrement the reference count. Must be called after try_module_get succeeds. */
void module_put(struct module *module);

When the consumer module is loaded and uses a symbol from the provider, the kernel internally calls try_module_get(provider_module). This increments the provider’s reference count from 0 to 1. When the consumer is unloaded, module_put(provider_module) is called and the count drops back to 0, making the provider removable.

You can check the current reference count of any module directly:

$ cat /sys/module/provider_module/refcnt
1

# See which modules are listed as holders (dependents)
$ ls /sys/module/provider_module/holders/
consumer_module

When Do You Call try_module_get Yourself?

Most driver developers never call try_module_get directly. The kernel subsystems handle it for you. For example, when a process opens a character device, the kernel calls fops_get() internally which does try_module_get(fops->owner). Your driver just sets .owner = THIS_MODULE in its file_operations structure and the reference counting works automatically.

static const struct file_operations ep_fops = {
    .owner   = THIS_MODULE,   /* kernel uses this for ref counting */
    .open    = ep_open,
    .release = ep_release,
    .read    = ep_read,
    .write   = ep_write,
};

You only need to call try_module_get and module_put manually when you store a function pointer from another module and call it later — for example in a plugin or callback architecture inside the kernel.

GPL License Enforcement — Two Layers of Defense

The kernel enforces GPL-only symbol access at two separate points. Getting blocked at either one means you cannot use the symbol.

ERROR: modpost: GPL-incompatible module consumer.ko uses GPL-only symbol 'ep_show_platform_info'

What MODULE_LICENSE Does Exactly

The kernel checks your declared license string against a fixed list inside include/linux/license.h. The function license_is_gpl_compatible() returns true only for these exact strings:

MODULE_LICENSE("GPL");                    /* GNU General Public License v2 or later */
MODULE_LICENSE("GPL v2");                 /* GNU General Public License v2 only     */
MODULE_LICENSE("GPL and additional rights");
MODULE_LICENSE("Dual BSD/GPL");
MODULE_LICENSE("Dual MIT/GPL");
MODULE_LICENSE("Dual MPL/GPL");

Anything else — including "Proprietary", "MIT", "BSD" alone, or any custom string — is treated as non-GPL. The kernel still loads the module but sets the P taint flag on the kernel.

You can check the current taint status of your running kernel at any time:

$ cat /proc/sys/kernel/tainted
0        # Zero means no taint — clean kernel

# After loading a proprietary module:
$ cat /proc/sys/kernel/tainted
4096     # Non-zero — kernel is tainted

Taint is sticky for the entire boot session. Even if you later unload the proprietary module, the taint bit remains set until the next reboot. This is important when reporting kernel bugs — a tainted kernel means the maintainers cannot fully trust the crash reports.

What Happens at the Boundary — GPL Module Using a Proprietary Module

The GPL enforcement also works in the other direction. If a GPL-licensed module tries to use symbols from a proprietary module, the kernel prints a warning and marks the GPL module as contaminated:

dmesg output:
consumer_module: module using GPL-only symbols uses symbols from proprietary module provider_module.

This is the kernel’s way of saying: you cannot wrap a GPL interface around a proprietary core. The intent is to prevent a common trick where a thin GPL shim module is used to expose proprietary functionality to the kernel.

Symbol Namespaces in Linux 6.x — A Newer Layer of Access Control

Starting with Linux 5.4, the kernel added a feature called symbol namespaces. This lets subsystem maintainers group their exported symbols under a named namespace and require consuming modules to explicitly declare that they are importing from that namespace.

Think of it as a second layer of access control on top of the GPL check. Even if your module is GPL-compatible, you still have to declare which namespaces you are importing from.

Exporting Into a Namespace

/* Linux 6.13+ — namespace is a quoted string */
EXPORT_SYMBOL_NS(ep_add, "EP_MATH");
EXPORT_SYMBOL_NS_GPL(ep_show_platform_info, "EP_INTERNAL");

Importing a Namespace in the Consumer

/* In consumer_module.c — must declare namespace imports */
MODULE_IMPORT_NS("EP_MATH");
MODULE_IMPORT_NS("EP_INTERNAL");

If the consumer does not declare the import, the kernel refuses to load it with EINVAL and dmesg shows:

consumer_module: module EP_MATH is not imported

During development, you can use make nsdeps in your kernel build directory and it will automatically add the correct MODULE_IMPORT_NS lines to your source files based on what your module actually uses.

The Full Dependency Pipeline — From Build to Runtime

Understanding the complete flow from writing code to a module running on the kernel helps you debug problems faster. Here is how the whole system works end to end:

What modules.dep Looks Like

After running depmod -a, the file /lib/modules/$(uname -r)/modules.dep contains lines like this:

kernel/extra/consumer_module.ko: kernel/extra/provider_module.ko

This means consumer_module.ko depends on provider_module.ko. When you run modprobe consumer_module, modprobe reads this file and loads provider_module first. Dependencies are listed right-to-left (rightmost must load first).

# Inspect dependencies of an installed module
$ modinfo consumer_module
filename:       /lib/modules/6.x.x/extra/consumer_module.ko
license:        GPL
depends:        provider_module
vermagic:       6.x.x SMP preempt mod_unload
import_ns:      EP_MATH

The depends: field shows what modules must be loaded first. The import_ns: field (Linux 6.x) shows which symbol namespaces this module imports from.

Linux 6.x Specific Changes to Module Infrastructure

If you have used older tutorials or books written for kernel 4.x or 5.x, there are a few important changes to be aware of when working on Linux 6.x.

EXPORT_SYMBOL_FOR_MODULES — New in 6.x

This is a new macro in 6.x that allows a symbol to be exported but restricted to a specific list of in-tree modules. It is mainly used by KVM and other subsystems that want tight control over who can use a particular internal function.

/* Only kvm and kvm-intel can use this symbol */
EXPORT_SYMBOL_FOR_MODULES(kvm_internal_helper, "kvm,kvm-intel");

/* Tail glob — kvm and any module starting with kvm- */
EXPORT_SYMBOL_FOR_MODULES(another_helper, "kvm,kvm-*");

These symbols are placed in a special namespace that cannot be imported by out-of-tree modules. They are GPL-only by design and cannot be used by external code at all. You will not need this for typical driver development, but it is useful to know when reading kernel source code.

Common Mistakes and How to Fix Them

/* Missing — causes Unknown symbol error */
int ep_helper(void) { return 42; }

/* Correct */
int ep_helper(void) { return 42; }
EXPORT_SYMBOL(ep_helper);

# Copy modules to the right place
$ sudo cp *.ko /lib/modules/$(uname -r)/extra/

# Rebuild the dependency database
$ sudo depmod -a

# Now modprobe works
$ sudo modprobe consumer_module

/* Add this to consumer_module.c */
MODULE_IMPORT_NS("PROVIDER_NAMESPACE");

Best Practices for Module Stacking

Useful Commands for Debugging Module Dependencies

# Show all loaded modules, their size, and their dependents
$ lsmod

# Show detailed info about a .ko file (before loading)
$ modinfo ./consumer_module.ko

# Show live kernel symbol table — grep for your symbol
$ sudo grep ep_add /proc/kallsyms

# Check reference count of a loaded module
$ cat /sys/module/provider_module/refcnt

# List modules that hold a reference to a module
$ ls /sys/module/provider_module/holders/

# Check the dependency file generated by depmod
$ cat /lib/modules/$(uname -r)/modules.dep | grep consumer

# See which processes have a device file open (if refcount is stuck > 0)
$ sudo lsof /dev/your_device

# Check kernel taint status
$ cat /proc/sys/kernel/tainted

# Show all namespaces imported by a module
$ modinfo consumer_module | grep import_ns

# Verbose modprobe — shows what is loaded and in what order
$ sudo modprobe -v consumer_module