The Hello World Linux Loadable Kernel Module

A kernel module is not an application — for a start there is no main() function! Some of the key differences are that kernel modules:

do not execute sequentially— a kernel module registers itself to handle requests using its initialization function, which runs and then terminates. The type of requests that it can handle are defined within the module code. This is quite similar to the event-driven programming model that is commonly utilized in graphical-user interface (GUI) applications.
do not have automatic cleanup — any resources that are allocated to the module must be manually released when the module is unloaded, or they may be unavailable until a system reboots.
do not have printf() functions — kernel code cannot access libraries of code that is written for the Linux user space. The kernel module lives and runs in kernel space, which has its own memory address space. The interface between kernel space and user space is clearly defined and controlled. We do however have a printk() function that can output information, which can be viewed from within user space.
can be interrupted — one conceptually difficult aspect of kernel modules is that they can be used by several different programs/processes at the same time. We have to carefully construct our modules so that they have a consistent and valid behavior when they are interrupted. The BeagleBone has a single-core processor (for the moment) but we still have to consider the impact of multiple processes accessing the module simultaneously.
have a higher level of execution privilege — typically, more CPU cycles are allocated to kernel modules than to user-space programs. This sounds like an advantage, however, you have to be very careful that your module does not adversely affect the overall performance of your system.
do not have floating-point support — it is kernel code that uses traps to transition from integer to floating-point mode for your user space applications. However, it is very difficult to perform these traps in kernel space. The alternative is to manually save and restore floating point operations — a task that is best avoided and left to your user-space code.

hello.c

```
/**
```
```
 * file    hello.c
```
```
 * author  J. Shankarappa
```
```
 * date    4 Nov 2019
```
```
 * version 0.1
```

 * An introductory "Hello World!" loadable kernel module (LKM) that can display a message

 * in the /var/log/kern.log file when the module is loaded and removed. The module can accept an

 * argument when it is loaded -- the name, which appears in the kernel log files.

```
*/
```

#include <linux/init.h>             /* Macros used to mark up functions e.g., __init __exit */

#include <linux/module.h>           /* Core header for loading LKMs into the kernel */

#include <linux/kernel.h>           /* Contains types, macros, functions for the kernel */

MODULE_LICENSE("GPL");              /* The license type -- this affects runtime behavior */

MODULE_AUTHOR("J.Shankarappa");     /* The author -- visible when you use modinfo */

MODULE_DESCRIPTION("A simple Linux driver for the BBB.");  /* The description -- see modinfo */

MODULE_VERSION("0.1");              /* The version of the module */

static char *name = "World";        /* An example LKM argument -- default value is "world" */

module_param(name, charp, S_IRUGO); /* Param desc. charp = char ptr, S_IRUGO can be read/not changed */

MODULE_PARM_DESC(name, "The name to display in /var/log/kern.log");  /* parameter description */

```
/** The LKM initialization function
```

 *  The static keyword restricts the visibility of the function to within this C file. The __init

 *  macro means that for a built-in driver (not a LKM) the function is only used at initialization

 *  time and that it can be discarded and its memory freed up after that point.

```
 *  
```
```
 * returns : 0 if successful
```
```
 */
```
```
static int __init helloBBB_init(void){
```

   printk(KERN_INFO "EmSys: Hello %s from the BBB LKM!\n", name);

```
   return 0;
```
```
}
```
```
/** The LKM cleanup function
```

 *  Similar to the initialization function, it is static. The __exit macro notifies that if this

 *  code is used for a built-in driver (not a LKM) that this function is not required.

```
 */
```
```
static void __exit helloBBB_exit(void){
```

   printk(KERN_INFO "EmSys: Goodbye %s from the BBB LKM!\n", name);

```
}
```

/** A module must use the module_init() and module_exit() macros from linux/init.h, which

 *  identify the initialization function at insertion time and the cleanup function (as

```
 *  listed above)
```
```
 */
```
```
module_init(helloBBB_init);
```
```
module_exit(helloBBB_exit);
```

Line 15: The statement MODULE_LICENSE(“GPL”) provides information (via modinfo) about the licensing terms of the module that you have developed, thus allowing users of your LKM to ensure that they are using free software. Since the kernel is released under the GPL, your license choice impacts upon the way that the kernel treats your module.
Line 20: The name (ptr to char) is declared as static and is initialized to contain the string “hello”. You should avoid using global variables in kernel modules — it is even more important than in application programming, as global variables are shared kernel wide. You should use the static keyword to restrict a variable’s scope to within the module. If you must use a global variable, add a prefix that is unique to the module that you are writing.
Line 21: The module_param(name, type, permissions) macro has three parameters: name (the parameter name displayed to the user and the variable name in the module), type (the type of the parameter — i.e., one of byte, int, uint, long, ulong, short, ushort, bool, an inverse Boolean invbool, or a char pointer charp), and permissions (this is the access permissions to the the parameter when using sysfs. A value of 0 disables the entry, but S_IRUGO allows read access for user/group/others — See the Mode Bits for Access Permissions Guide)
Line 30 and 39: The functions can have whatever names you like (e.g., helloBBB_init() and helloBBB_exit()), however, the same names must be passed to the special macros module_init() and module_exit() on lines 48 and 49.
Line 32: The printk() is very similar in usage to the printf() function that you should be familiar with, and you can call it from anywhere within the kernel module code. The only significant difference is that you should specify a log level when you call the function. The log levels are defined in linux/kern_levels.h as one of KERN_EMERG, KERN_ALERT, KERN_CRIT, KERN_ERR, KERN_WARNING, KERN_NOTICE, KERN_INFO, KERN_DEBUG, and KERN_DEFAULT. This header is included via the linux/kernel.h header file, which includes it via linux/printk.h.

Essentially, when this module is loaded the helloBBB_init() function will execute, and when the module is unloaded the helloBBB_exit() function will execute.

Building the Module Code

A Makefile is required to build the kernel module — in fact, it is a special kbuild Makefile. The kbuild Makefile required to build the kernel module is shown below:

Makefile

```
MODULES := hello.o
```
```
#guest architecture
```
```
ARCH := arm
```
```
CROSS_COMPILE := arm-linux-gnueabihf-
```
```
obj-m := $(MODULES)
```
```
# path of the arm compiled kernel
```
```
KDIR := /path/to/compiled/linux/kernel
```

DESTDIR := /path/to/compiled/kernel/target

MAKEARCH := $(MAKE) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE)

```
all: modules
```
```
modules:
```

	$(MAKEARCH) -C $(KDIR) M=${shell pwd} modules

```
install:
```

	$(MAKE) -C $(KDIR) M=$(PWD) INSTALL_MOD_PATH=$(DESTDIR) modules_install

```
clean:
```

	$(MAKEARCH) -C $(KDIR) M=${shell pwd} clean

Line 7 of this Makefile is called a goal definition and it defines the module to be built (hello.o). obj-m defines a loadable module goal, whereas obj-y indicates a built-in object goal.
Line 17: The -C option switches the directory to the kernel directory before performing any make tasks. The M=${shell pwd} variable assignment tells the make command where the actual project files exist.
The modules target is the default target for external kernel modules. An alternative target is modules_install which would install the module (the make command would have to be executed with superuser permissions and the module installation path is required).

$ make

The Hello World Linux Loadable Kernel Module

hello.c

Building the Module Code

Makefile

Testing the LKM

Recent Posts

Recent Comments