Introduction
Loadable Kernel Modules (LKM) are object code that can be loaded into memory, often used for supporting hardware or enable specific features. Kernel modules enable the core kernel to be minimal and have features to be loaded as required.
A kernel module is a normal file usually suffixed with .ko
denoting it’s a kernel object file. It contains compiled code from one or more source files, gets linked to the kernel when loaded, and runs in kernel space. It can dynamically adds functionality to a running kernel, without requiring a reboot.
Linux kernel modules are written in C (not sure if anything else like C++ is possible), and is compiled for a specific kernel version. This is the ideal practice since kernel data structures may change across versions, and using a module compiled for a specific version may break for another.
Since kernel modules can be loaded and unloaded at will, it is pretty easy to unload an older version and load a newer one. This helps immensely in testing out new features since it is easy to change the source code, re-compile, unload the older version, load the newer version, and test the functionality.
Structure
Modules are expected to be under /lib/modules/$(uname -r)/
within directories specified according to use case.
[root@centos7 3.10.0-514.26.2.el7.x86_64]# ls -l total 2940 lrwxrwxrwx. 1 root root 43 Jul 8 05:10 build -> /usr/src/kernels/3.10.0-514.26.2.el7.x86_64 drwxr-xr-x. 2 root root 6 Jul 4 11:17 extra drwxr-xr-x. 12 root root 128 Jul 8 05:10 kernel -rw-r--r--. 1 root root 762886 Jul 8 05:11 modules.alias -rw-r--r--. 1 root root 735054 Jul 8 05:11 modules.alias.bin -rw-r--r--. 1 root root 1326 Jul 4 11:17 modules.block -rw-r--r--. 1 root root 6227 Jul 4 11:15 modules.builtin -rw-r--r--. 1 root root 8035 Jul 8 05:11 modules.builtin.bin -rw-r--r--. 1 root root 240071 Jul 8 05:11 modules.dep -rw-r--r--. 1 root root 343333 Jul 8 05:11 modules.dep.bin -rw-r--r--. 1 root root 361 Jul 8 05:11 modules.devname -rw-r--r--. 1 root root 132 Jul 4 11:17 modules.drm -rw-r--r--. 1 root root 110 Jul 4 11:17 modules.modesetting -rw-r--r--. 1 root root 1580 Jul 4 11:17 modules.networking -rw-r--r--. 1 root root 90643 Jul 4 11:15 modules.order -rw-r--r--. 1 root root 89 Jul 8 05:11 modules.softdep -rw-r--r--. 1 root root 350918 Jul 8 05:11 modules.symbols -rw-r--r--. 1 root root 432831 Jul 8 05:11 modules.symbols.bin lrwxrwxrwx. 1 root root 5 Jul 8 05:10 source -> build drwxr-xr-x. 2 root root 6 Jul 4 11:17 updates drwxr-xr-x. 2 root root 95 Jul 8 05:10 vdso drwxr-xr-x. 2 root root 6 Jul 4 11:17 weak-updates
As we can see, there are several files that deals with the inter-dependencies of modules, which is used by modprobe
to understand which modules to load before the one being actually requested to load.
For example:
modules.block
lists the modules for block devicesmodules.networking
lists the ones for network devices.modules.builtin
lists the path of modules included in the kernel.modules.devname
lists the ones that would be loaded automatically if a particular device is created.
The kernel folder contains modules divided according to their use cases.
[root@centos7 3.10.0-514.26.2.el7.x86_64]# ls -l kernel/ total 16 drwxr-xr-x. 3 root root 17 Jul 8 05:10 arch drwxr-xr-x. 3 root root 4096 Jul 8 05:10 crypto drwxr-xr-x. 67 root root 4096 Jul 8 05:10 drivers drwxr-xr-x. 26 root root 4096 Jul 8 05:10 fs drwxr-xr-x. 3 root root 19 Jul 8 05:10 kernel drwxr-xr-x. 5 root root 222 Jul 8 05:10 lib drwxr-xr-x. 2 root root 32 Jul 8 05:10 mm drwxr-xr-x. 33 root root 4096 Jul 8 05:10 net drwxr-xr-x. 11 root root 156 Jul 8 05:10 sound drwxr-xr-x. 3 root root 17 Jul 8 05:10 virt
Each directory within kernel contains modules depending on the area they’re used for. For example, kernel/fs/
contains filesystem drivers.
[root@centos7 3.10.0-514.26.2.el7.x86_64]# ls -l kernel/fs total 48 -rw-r--r--. 1 root root 21853 Jul 4 11:51 binfmt_misc.ko drwxr-xr-x. 2 root root 22 Jul 8 05:10 btrfs drwxr-xr-x. 2 root root 27 Jul 8 05:10 cachefiles drwxr-xr-x. 2 root root 21 Jul 8 05:10 ceph drwxr-xr-x. 2 root root 21 Jul 8 05:10 cifs drwxr-xr-x. 2 root root 23 Jul 8 05:10 cramfs drwxr-xr-x. 2 root root 20 Jul 8 05:10 dlm drwxr-xr-x. 2 root root 23 Jul 8 05:10 exofs drwxr-xr-x. 2 root root 21 Jul 8 05:10 ext4 drwxr-xr-x. 2 root root 51 Jul 8 05:10 fat drwxr-xr-x. 2 root root 24 Jul 8 05:10 fscache drwxr-xr-x. 2 root root 36 Jul 8 05:10 fuse drwxr-xr-x. 2 root root 21 Jul 8 05:10 gfs2 drwxr-xr-x. 2 root root 22 Jul 8 05:10 isofs drwxr-xr-x. 2 root root 21 Jul 8 05:10 jbd2 drwxr-xr-x. 2 root root 22 Jul 8 05:10 lockd -rw-r--r--. 1 root root 19597 Jul 4 11:51 mbcache.ko drwxr-xr-x. 6 root root 128 Jul 8 05:10 nfs drwxr-xr-x. 2 root root 40 Jul 8 05:10 nfs_common drwxr-xr-x. 2 root root 21 Jul 8 05:10 nfsd drwxr-xr-x. 2 root root 4096 Jul 8 05:10 nls drwxr-xr-x. 2 root root 24 Jul 8 05:10 overlayfs drwxr-xr-x. 2 root root 24 Jul 8 05:10 pstore drwxr-xr-x. 2 root root 25 Jul 8 05:10 squashfs drwxr-xr-x. 2 root root 20 Jul 8 05:10 udf drwxr-xr-x. 2 root root 20 Jul 8 05:10 xfs
depmod, and related commands
Modules can export the features it carry, called symbols
which can be used by other modules. If module A
depends on a symbol exported by module B
, module B
should be loaded first followed by module A
.
depmod
creates a list of symbol dependencies each module has, so that modprobe
can go ahead and load the modules serving the symbols, prior loading the actual module.
depmod
works by:
- Creating a list of symbols each module exports.
- Creating a list of symbol dependencies each module has.
- Dumping the list of symbols each module exports, to
lib/modules/$(uname -r)/modules.symbols.bin
and/lib/modules/$(uname -r)/modules.symbols
- Dumping the module dependency information to
/lib/modules/$(uname -r)/modules.dep.bin
and/lib/modules/$(uname -r)/modules.dep
. - Creating
/lib/modules/$(uname -r)/modules.devnames
which contains the device file information (device type, major:minor number) that gets created at boot for this module to function properly.
NOTE:
modprobe
refers/lib/modules/$(uname -r)/modules.dep.bin
to understand the dependencies each module require. A human-readable version of this file is maintained at/lib/modules/$(uname -r)/modules.dep
butmodprobe
does not refer this.- The binary file
modules.symbols.bin
carry the symbols exported (if any) by each module, one symbol per line. A human-readable version of the same is kept atmodules.symbols
.
A sneak peek into modules.symbols
and modules.dep
:
modules.symbols
[root@centos7 3.10.0-514.26.2.el7.x86_64]# head modules.symbols # Aliases for symbols, used by symbol_request(). alias symbol:cfg80211_report_obss_beacon cfg80211 alias symbol:drm_dp_link_train_channel_eq_delay drm_kms_helper alias symbol:__twofish_setkey twofish_common alias symbol:mlx4_db_free mlx4_core alias symbol:nf_send_unreach nf_reject_ipv4 alias symbol:sdhci_remove_host sdhci alias symbol:videobuf_dma_init_kernel videobuf_dma_sg alias symbol:ar9003_paprd_is_done ath9k_hw alias symbol:cxgbi_ep_disconnect libcxgbi
modules.dep
[root@centos7 3.10.0-514.26.2.el7.x86_64]# head modules.dep kernel/arch/x86/kernel/cpu/mcheck/mce-inject.ko: kernel/arch/x86/kernel/test_nx.ko: kernel/arch/x86/kernel/iosf_mbi.ko: kernel/arch/x86/crypto/ablk_helper.ko: kernel/crypto/cryptd.ko kernel/arch/x86/crypto/glue_helper.ko: kernel/arch/x86/crypto/camellia-x86_64.ko: kernel/crypto/xts.ko kernel/crypto/lrw.ko kernel/crypto/gf128mul.ko kernel/arch/x86/crypto/glue_helper.ko kernel/arch/x86/crypto/blowfish-x86_64.ko: kernel/crypto/blowfish_common.ko kernel/arch/x86/crypto/twofish-x86_64.ko: kernel/crypto/twofish_common.ko kernel/arch/x86/crypto/twofish-x86_64-3way.ko: kernel/arch/x86/crypto/twofish-x86_64.ko kernel/crypto/twofish_common.ko kernel/crypto/xts.ko kernel/crypto/lrw.ko kernel/crypto/gf128mul.ko kernel/arch/x86/crypto/glue_helper.ko kernel/arch/x86/crypto/salsa20-x86_64.ko:
lsmod
is a parser that reads through /proc/modules
and presents it in an easy-to-read format.
Note how lsmod
parse throug the content of /proc/modules
below:
[root@centos7 3.10.0-514.26.2.el7.x86_64]# head /proc/modules test 12498 0 - Live 0xffffffffa0492000 (POE) binfmt_misc 17468 1 - Live 0xffffffffa048c000 uhid 17369 0 - Live 0xffffffffa0486000 ipt_MASQUERADE 12678 2 - Live 0xffffffffa0481000 nf_nat_masquerade_ipv4 13412 1 ipt_MASQUERADE, Live 0xffffffffa0451000 xt_addrtype 12676 2 - Live 0xffffffffa044c000 br_netfilter 22209 0 - Live 0xffffffffa0468000 dm_thin_pool 65565 1 - Live 0xffffffffa046f000 dm_persistent_data 67216 1 dm_thin_pool, Live 0xffffffffa0456000 dm_bio_prison 15907 1 dm_thin_pool, Live 0xffffffffa043f000 [root@centos7 3.10.0-514.26.2.el7.x86_64]# lsmod | head Module Size Used by test 12498 0 binfmt_misc 17468 1 uhid 17369 0 ipt_MASQUERADE 12678 2 nf_nat_masquerade_ipv4 13412 1 ipt_MASQUERADE xt_addrtype 12676 2 br_netfilter 22209 0 dm_thin_pool 65565 1 dm_persistent_data 67216 1 dm_thin_pool
NOTE:
- The first field lists the module name.
- The second field lists the size of the module in memory.
- The third field lists the number of times the module is in use. `0` means the module is not used despite it being loaded.
- The fourth field lists the modules which uses this module as their dependency.
Creating a dummy module
The steps for creating a kernel module includes:
- Writing the module file.
- Writing the
Makefile
for the module. - Compile the module file using
make
, which will refer theMakefile
to build it.
The module file and its corresponding Makefile are put in a separate directory so as to keep the kernel module directory clean. Once the module code and the Makefile are ready, the following make
command is used to build the module, the $(PWD)
being the directory where the module code and its Makefile is present.
# make -C /lib/modules/$(uname -r)/build M=$PWD modules
The make
command above does the following:
- Change to the path mentioned after
-C
, ie.. to the location where the kernel Makefile is present. (/lib/modules/$(uname -r)/build/
) - Use the kernel Makefile’s macro
M
which denotes the location from which the code should be compiled, ie.. in this case, the PWD where the module code/Makefile is present. - Use the target
modules
which tellsmake
to build the module.
Hence, the above command is trying to build a module in the current working directory, using the kernel Makefile at /lib/modules/$(uname -r)/build/Makefile
If we have a module file named test.c
and its corresponding Makefile in $(PWD)
, the make
command would follow the steps below:
make
calls themodules
target and refers to the kernelMakefile
.- The kernel Makefile looks for the module Makefile in $PWD.
- The kernel Makefile read the module’s Makefile and gets a list of the objects assigned to the macro
obj-m
. - The
make
command builds modules for each object assigned to the macroobj-m
.
Writing a simple module
The following is a very simple module, which prints a message while loading, and another one while unloading.
#include #include #include int test_module(void) { printk("Loading the test module!\n"); return 0; } void unload_test(void) { printk("Unloading the test module!\n"); } module_init(test_module) module_exit(unload_test)
This has two functions, test_module()
and unload_test()
which simply prints a text banner upon loading and unloading respectively.
module_init()
is used to load the module, and can call whatever functions that needs to initialize the module. We load our test_module()
function into module_init()
so that it gets initialized when the module is loaded.
module_exit()
is called whenever the module has to be unloaded, and it can take in whatever functions are required to do a proper cleanup (if required) prior the module being unloaded. We load our unload_test()
function in module_exit()
.
Writing a Makefile
Since the kernel Makefile will look in for the obj-m
macro in the module Makefile with the object filename as its argument, add the following in the Makefile:
obj-m := test.o
make
will create an object file test.o
from test.c
, and then create a kernel object file test.ko
.
Compiling the module with `make`
Let’s compile the module
[root@centos7 test]# pwd /lib/modules/3.10.0-514.26.2.el7.x86_64/test [root@centos7 test]# ls Makefile test.c [root@centos7 test]# make -C /lib/modules/$(uname -r)/build M=$PWD modules make: Entering directory `/usr/src/kernels/3.10.0-514.26.2.el7.x86_64' CC [M] /lib/modules/3.10.0-514.26.2.el7.x86_64/test/test.o Building modules, stage 2. MODPOST 1 modules CC /lib/modules/3.10.0-514.26.2.el7.x86_64/test/test.mod.o LD [M] /lib/modules/3.10.0-514.26.2.el7.x86_64/test/test.ko make: Leaving directory `/usr/src/kernels/3.10.0-514.26.2.el7.x86_64'
Listing the contents show lot of new files, including the module code, the Makefile, the object file test.o
created from test.c
, the kernel object file test.ko
.
test.mod.c
contains code which should be the one ultimately being built to test.ko
, but that should be for another post since much more is yet to be read/learned on what’s happening there.
[root@centos7 test]# ls -l total 292 -rw-r--r--. 1 root root 16 Jul 27 11:52 Makefile -rw-r--r--. 1 root root 60 Jul 27 11:57 modules.order -rw-r--r--. 1 root root 0 Jul 27 11:57 Module.symvers -rw-r--r--. 1 root root 281 Jul 27 11:53 test.c -rw-r--r--. 1 root root 137768 Jul 27 11:57 test.ko -rw-r--r--. 1 root root 787 Jul 27 11:57 test.mod.c -rw-r--r--. 1 root root 52912 Jul 27 11:57 test.mod.o -rw-r--r--. 1 root root 87776 Jul 27 11:57 test.o
Loading/Unloading the module
Loading and unloading the module should print the messages passed via printk
in dmesg
.
[root@centos7 test]# insmod ./test.ko [root@centos7 test]# lsmod | grep test test 12498 0 [root@centos7 test]# rmmod test
Checking dmesg
shows the informational messages in the module code:
[root@centos7 test]# dmesg | tail [35889.187282] test: loading out-of-tree module taints kernel. [35889.187288] test: module license 'unspecified' taints kernel. [35889.187290] Disabling lock debugging due to kernel taint [35889.187338] test: module verification failed: signature and/or required key missing - tainting kernel [35889.187548] Loading the test module! [35899.216954] Unloading the test module!
Note the messages about the module test
tainting the kernel. Read more on how a module can taint the kernel, at https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html.
More on customizing the Makefile in another post.
This is great. It will be refresher course for me[1]. Looking forward to it.
[1] https://github.com/psachin/kernel_modules
> not sure if anything else like C++ is possible
It is possible but Linus hates[1] C++
[1] http://harmful.cat-v.org/software/c++/linus
Sachin, Thank you for clarifying this. 🙂