Introduction to Android Kernel Modules

Loadable Kernel Modules (LKMs) are fundamental components for extending the functionality of the Linux kernel without requiring a full system reboot. In the Android ecosystem, LKMs are crucial for custom drivers, security research, rootkits, and specialized system enhancements. However, loading LKMs on Android devices often presents unique challenges due to diverse hardware, varied kernel configurations, strict security policies (like SELinux), and fragmented toolchains. This handbook provides an expert-level guide to diagnosing and resolving the most common LKM loading errors encountered by Android developers.

Before diving into specific errors, it’s essential to understand the primary utility for loading modules: insmod. While Linux distributions often use modprobe which handles dependencies automatically, Android typically relies on a simpler insmod which expects the module to be self-contained or its dependencies already loaded.

Error Category 1: Kernel Version and ABI Mismatches

Symptoms:

• insmod: ERROR: could not insert 'my_module.ko': Invalid module format
• insmod: ERROR: could not insert 'my_module.ko': Module has no symbol table
• Unexpected kernel panic or device freeze during `insmod`

Cause:

This is arguably the most frequent issue. Android kernels are highly customized, and LKMs must be compiled against the exact kernel source code and configuration of the target device. A mismatch in kernel version, GCC compiler version, or kernel configuration options (especially CONFIG_MODVERSIONS) will lead to these errors. The kernel’s `vermagic` string, which embeds critical build information, is compared during loading.

Troubleshooting Steps:

1. Identify Target Kernel Version: On your Android device, use adb shell uname -r to get the kernel release string. For example: 4.14.117-g0d7696e-dirty.
2. Examine Module’s Vermagic: Use readelf or modinfo (if available on your build host) to check your compiled module’s `vermagic`.

   $ readelf -s my_module.ko | grep vermagic

   Or, if you have modinfo available in your cross-compilation environment:

   $ PATH=/path/to/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH modinfo -F vermagic my_module.ko

   The output (e.g., 4.14.117-g0d7696e-dirty SMP preempt mod_unload aarch64) must precisely match the target kernel’s `uname -r` string (up to the ABI version part). Even minor discrepancies (like `-dirty` suffix, or different GCC versions) can cause issues.

3. Verify Kernel Source and Configuration: Ensure you are building your LKM against the exact kernel source tree and .config file used to build your device’s kernel. Many manufacturers release kernel sources; use them. Pay attention to the CROSS_COMPILE and ARCH variables in your module’s Makefile to match the target.
4. Disable/Enable CONFIG_MODVERSIONS (if necessary): If your module’s `vermagic` consistently differs due to symbol CRC mismatches, and you have control over the kernel build, consider aligning CONFIG_MODVERSIONS. While generally good for stability, it can be a source of frustration if toolchains aren’t perfectly aligned.

Error Category 2: Symbol Resolution Issues

Symptoms:

• insmod: ERROR: could not insert 'my_module.ko': Unknown symbol in module (module_function)
• insmod: ERROR: could not insert 'my_module.ko': undefined symbol: some_kernel_function

Cause:

Your LKM is attempting to use a kernel function or variable that is not exported by the kernel or by other loaded modules it depends on. This can happen if you’re calling a kernel internal function, using a function introduced in a newer kernel version, or if a prerequisite module hasn’t been loaded yet.

Troubleshooting Steps:

1. Check Kernel Exports: The kernel exports its symbols for modules to use. You can inspect available symbols on a rooted device via /proc/kallsyms.

   $ adb shell 'grep
   
           
           
           
   
               
   
                   
               
               
   
                   
   Android Mobile Specs & Compare Directory
                   
   Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!
                   Compare Devices Specs →