Sogang University Advanced Operating Systems (Linux Module Programming) Sang Gue Oh, Ph.D.

Sogang University Linux Module Programming Page 2 Motivation of Modules Motivation of Modules n Linux kernel is a monolithic kernel. n The limitation of a monolithic kernel. t When the configuration is changed, the kernel has to be compiled. t The rarely used file systems and drivers occupy memory permanently. t The kernel code modification results in creating the new kernel and rebooting the system n This leads to the development of modules.

Sogang University Linux Module Programming Page 3 What is a Module ? n Linux module : t is a functional unit such as file system or driver. t can be dynamically linked into the kernel at any point after the system has booted. => the loaded modules are regarded as the kernel. t can be removed from the kernel when it is no longer needed. t When a module is loaded, it is same as a kernel. n This results in small and compact kernel size and the ability of trying out new kernel code without rebuilding and rebooting the kernel. n CONFIG_KERNELD and System V IPC options should be enabled to use modules in Linux.

Sogang University Linux Module Programming Page 4 Module Data Structure (1) n The loaded modules are maintained by module data structure. n Each module data structure points to the symbol table structure that contains all symbols of the module. n The kernel symbol table is pointed by the first module data structure.

Sogang University Linux Module Programming Page 5 The list of kernel modules module next ref symtab size references kernel symbol table “kernel symbol table module” module next ref symtab size references “sysv module” sysv symbol table module_list Module Data Structure (2)

Sogang University Linux Module Programming Page 6 Minimum Module Interface Minimum Module Interface #include ….. int init_module() { /* Code to initialize the module when it is installed */ } void cleanup_module() { /* Code to clean up when the module is removed */ }

Sogang University Linux Module Programming Page 7 Using Macros (After Linux 2.4) Using Macros (After Linux 2.4) #include #include // Needed for the macros ….. static int hello_init_(void) { /* Code to initialize the module when it is installed */ } static void hello_exit(void) { /* Code to clean up when the module is removed */ } module_init(hello_init);// hello_init should be defined before this macro module_exit(hello_exit);// hello_exit should be defined before this macro

Sogang University Linux Module Programming Page 8 Compiling a Module Compiling a Module n A Kernel module is not an independent executable, but an object file which will be linked into the kernel in runtime. n As a result, they should be compiled with the -c flag. n Also use –W option (turn on warnings) and –O option (optimize). n All kernel modules have to be compiled with certain symbols defined (i.e., with -D option). t __KERNEL__ - This tells the header files that this code will be run in kernel mode, not as part of a user process (i.e., -D__KERNEL__). t MODULE - This tells the header files that this file is a module rather than an ordinary file (i.e., -DMODULE).

Sogang University Linux Module Programming Page 9 Version Dependency Version Dependency n Module’s code has to be recompiled for each version of the kernel that it will be linked to. t Each module defines a symbol called kernel-version, which insmod matches against the version number of the current kernel. Recent kernels define the symbol for you in. t Sometimes it makes sense to divide a kernel module between several source files. In this case, you need to do the following: l In all source files but one, add the line #define __NO_VERSION__ because of the global variable declaration of module.h. l Compile all the source files as usual. l Combine all the object files into a single one. Under x86, do it with ld -m elf i386 -r -o name-of-module.o 1st-file.o 2nd-file.o

Sogang University Linux Module Programming Page 10 Loading a Module (1) Loading a Module (1) n Two ways of loading a module t Manual loading : uses insmod command (e.g., insmod ). t On-demand loading : if the kernel discovers the need for loading a module (e.g., user mounts a file system), it requests kerneld daemon to load the needed module using message queue. kerneld loads that module using modprobe command. Mechanism of loading t Fixes up unresolved references to kernel routines and resources using the exported symbols from the kernel. t Requests the kernel for enough space to hold the new kernel. t The kernel allocates a new module data structure and enough kernel memory to hold the new module and puts it at the end of the kernel modules list.

Sogang University Linux Module Programming Page 11 Loading a Module (2) Loading a Module (2) t insmod copies the module into the allocated space and relocates it so that it will run from the kernel address that it has been allocated. t The new module exports symbols to the kernel and insmod builds a table of these exported symbols. t The new module depends on another module, that module has the reference of the new module. t The kernel calls the modules initialization routine (init_module())and carries on installing the module.

Sogang University Linux Module Programming Page 12 Communication between Kernel and Kerneld Communication between Kernel and Kerneld KernelKernelKernel kerneldkerneld kerneld modprobe fat KERNELD_REQUEST_MODULE fat Module loaded fat

Sogang University Linux Module Programming Page 13 Unloading a Module n Two ways of unloading a module t Manual unloading : uses rmmod command. t On-demand unloading : when idle timer expires, the kerneld calls the service routines for all unused loaded modules. n Mechanism of unloading t If the module can be unloaded, its cleanup routine (cleanup_module()) is called to free up the kernel resources that it has allocated. t The module data structure is unlinked from the list of kernel modules. t All of the kernel memory that the module needed is de-allocated.

Sogang University Linux Module Programming Page 14 Listing Current Modules (/proc/modules) Listing Current Modules (/proc/modules) dcclab# insmod fat dcclab# lsmod Module:#pages (or Size)Used by: fat60 dcclab# rmmod fat dcclab# lsmod Module:#pages Used by: dcclab# lsmod Module:#pagesUsed by: dcclab# mount -t msdos /dev/fd0 /mnt dcclab# lsmod Module:#pagesUsed by: msdos21 (autoclean) fat6[msdos]1 (autoclean) dcclab# ls -al /mnt …….. dcclab# unmount /mnt dcclab# lsmod Module:#pagesUsed by: msdos20 (autoclean) fat6[msdos]0 (autoclean) dcclab# sleep 60 dcclab# lsmod Module:#pagesUsed by:

Sogang University Linux Module Programming Page 15 Exporting Symbols (1) Exporting Symbols (1) n The public symbol table (kernel symbol table) can be read from /proc/ksyms. n When a module is loaded, any global symbol we declare becomes part of the kernel symbol table by default. n An alternative to exporting all the global symbols of a module is to use the function register_symtab. static struct symbol_table syms = { #include X(fn1), X(fn2), X(variable1), #include }; register_symtab(&syms);

Sogang University Linux Module Programming Page 16 Exporting Symbols (2) Exporting Symbols (2) n register_symtab replaces the public symbols exported by default for the current module with the explicit symbol table. n If we don’t want to declare everything as static, just hide global symbols by adding register_symtab(NULL) to the init_module(). n If the source file does not offer hooks for additional modules to be stacked on it, it’s always a good idea to hide all the symbols by using the line above. n New macros in the newer kernel (after 2.1.8) t REGISTER_SYMTAB(&name) -> register_symtab(&name); t EXPORT_SYMBOL(name) -> register name in the symbol table. t EXPORT_NO_SYMBOLS -> register_symtab(NULL);

Sogang University Linux Module Programming Page 17 Module Usage Counter Module Usage Counter n Each module has a usage counter to determine whether the module can be safely removed. n A module can’t be unloaded if it is busy. n The usage counter is maintained by three macros: t MOD_INC_USE_COUNT : increments the count for the current module. t MOD_DEC_USE_COUNT : decrements the count. t MOD_IN_USE : evaluates to true if the count is not zero. n There is not need to check for MOD_IN_USE from within cleanup_module, because the check is performed by the system. n Can’t unload a module if we lose track of the usage counter. t Completely disable the usage count during the debugging cycle. t Force the counter to zero (by ioctl).

Sogang University Linux Module Programming Page 18 Module Dependency Module Dependency n A module (B) can refer to the symbols exported by another module (A). n In this case, we say that B is loaded on top of A, or equivalent that A is used by B. n In order to link module B, module A must have already been linked; otherwise, the references to the symbols exported by A cannot be properly linked by B. n In short, there is a dependency between modules. n In order to ensure that module A is not removed before B, A’s usage counter is incremented for each module loaded on top of it. n Stacking modules is an effective way to modularize the kernel source code to speed up its development and improve its portability.

Sogang University Linux Module Programming Page 19 Example (hello.c) (1) /* The necessary header files */ #include /* We're doing kernel work */ #include /* Specifically, a module */ /* Deal with CONFIG_MODVERSIONS */ #if CONFIG_MODVERSIONS==1 #define MODVERSIONS #include => version management for the exported symbols #endif

Sogang University Linux Module Programming Page 20 Example (hello.c) (2) /* Initialize the module */ int init_module() { printk("Hello, world - this is the kernel speaking\n"); /* If we return a non zero value, it means that init_module failed and the kernel module can't be loaded */ return 0; } /* Cleanup - undid whatever init_module did */ void cleanup_module() { printk("Short is the life of a kernel module\n"); }

Sogang University Linux Module Programming Page 21 Makefile for hello.c Makefile for hello.c # Makefile for a basic kernel module CC = gcc MODFLAGS = -Wall -DMODULE -D__KERNEL__ hello.o : hello.c /usr/include/linux/version.h $(CC) $(MODFLAGS) -c hello.c echo insmod hello.o to turn it on echo rmmod hello to turn it off echo X and kernel programming do not mix. echo Do the insmod and rmmod from outside of X.

Sogang University Linux Module Programming Page 22 Use of Modules Use of Modules n Modules are usually used to implement device drivers. n However, they can be used to implement any desired functions. n Two types of interfaces are available to the designer to use with modules: t device driver.  /proc file system.