Parking and Unparking Kthread

Version Info

#	Version
Ubuntu	Ubuntu 22.10
Kernel	6.7.9

Learnings in this section

In this program, you are going to learn

How to create the kernel thread ?

How to park and unpark the kernel thread?

How to stop the kernel thread ?

How to use Kthread APIs ?

How to use below APIs ?

Explanation of Kthread APIs

kthread_should_stop

Here is the function prototype of the API: kthread_should_stop

#include <linux/kthread.h>

bool kthread_should_stop(void);

where
- kthread_should_stop: this is used to determine whether the thread should return now. Whenever the kthread_stop() is called it will be woken and returns true.
- return type: returns true when the thread is stopped, false when the thread is still in execution
Here is an example of how to use the API,

while (!kthread_should_stop())
{
    //add the instructions to be performed during thread execution.
}

kthread_run

Here is the function prototype of the API: kthread_run

#include <linux/kthread.h>

#define kthread_run(threadfn, data, namefmt, ...)

where
- kthread_run : is used to create and wake a kthread
- return type: struct task_struct* (i.e) address of the kthread
- threadfn: function to executed by kthread
- data: data pointer for threadfn which can be used to send any possible arguments required for threadfn.
- namefmt: printf-style format for the thread name which will be displayed on ps output when the thread is in execution.
Here is an example of how to use the API,

kthread_run(mythread,NULL,"sample kthread");

kthread_park

Here is the prototype of the API: kthread_park

#include <linux/kthread.h>

int kthread_park(struct task_struct *k);

where
- kthread_park : park a thread.
- k: thread which needs to be parked
- return type: returns 0 on success, -ENOSYS if the thread exited.
Here is the example of the API,

kthread_park(mythread);

kthread_unpark

Here is the prototype of the API: kthread_unpark

#include <linux/kthread.h>

void kthread_unpark(struct task_struct *k);

where
- kthread_unpark : unpark a thread
- k: thread which needs to be unparked.
Here is the example of the API,

kthread_unpark(mythread);

kthread_parkme

Here is the prototype of the API: kthread_parkme

#include <linux/kthread.h>

void kthread_parkme(void);

where
- kthread_parkme : will change the state of thread to TASK_PARKED

kthread_should_park

Here is the prototype of the API: kthread_should_park

#include <linux/kthread.h>

bool kthread_should_park(void);

where
- kthread_should_park : this keeps the thread alive and in a park position. kthread_unpark() “restarts” the thread and calls the thread function again.
- return type: returns true when kthread_park is called, false otherwise.

kthread_stop

Here is the function prototype of the API: kthread_stop

#include <linux/kthread.h>

int kthread_stop(struct task_struct *k);

where
- kthread_stop: stops a kthread.
- return type: returns the return value of threadfn() which is passed as an argument during kthread creation.
- k: kthread created by one of the API used to created kthread.
Here is the example of how to use the API,

kthread_stop(mythread);

Explanation of miscellaneous APIs

Module parameter APIs

Here is the prototype of module paramter APIs

#include <linux/module.h>

#define MODULE_LICENSE(_license) MODULE_FILE MODULE_INFO(license, _license)
#define MODULE_AUTHOR(_author) MODULE_INFO(author, _author)
#define MODULE_DESCRIPTION(_description) MODULE_INFO(description, _description)

where
- MODULE_LICENSE: tells the kernel what license is used by our module.
- MODULE_AUTHOR: denotes the author of this kernel module.
- MODULE_DESCRIPTION: gives a basic idea about what the kernel module does.
- These information can be found when modinfo command is used which lists out all these above mentioned information.
Here is the example of how to use the Module parameter APIs,

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Linux Usr");
MODULE_DESCRIPTION("Sample kernel module");

IS_ERR

Here is the prototype of the API: IS_ERR

#include <linux/err.h>

static inline bool __must_check IS_ERR(__force const void *ptr);

where
- IS_ERR: Detects an error pointer
- return type: return true if it’s an error pointer else return false.
- ptr: pointer which needs to detected.
Here is an example of how to use the API,

if(IS_ERR(sample_ptr)) {
    //instructions to be executed when error ptr is detected
} else {
    //instructions to be executed when error ptr is not detected
}

pr_info

Here is the prototype of the API: pr_info

#include <linux/printk.h>

#define pr_info(fmt, ...) \
    printk(KERN_INFO pr_fmt(fmt), ##__VA_ARGS__)

where
- pr_info: Prints an info-level messages
- fmt: format string
Here is an example of how to use the API,

pr_info("//sample print statement");

wake_up_process

Here is the example of the API: wake_up_process

#include <linux/sched.h>

extern int wake_up_process(struct task_struct *tsk);

where
- wake_up_process: wake up a specific process
- return type: returns 1 if the process is woken up, 0 if the process is in running state.
- tsk: process to be woken up.
Here is the example of how to use the API,

wake_up_process(mythread);

msleep

Here is the example of the API: msleep

#include <linux/delay.h>

void msleep(unsigned int msecs);

where
- msleep: will put it in sleep for a certain amount of msecs time.
- msecs: time in milliseconds to sleep for
Here is the example of how to use the API,

msleep(1000);

Driver entry point API’s

Here is the prototype of the Driver entry point API’s

#include <linux/module.h>

#define module_init(x)      __initcall(x);
#define module_exit(x)      __exitcall(x);

where
- module_init: driver initialization entry point which will be called at module insertion time.
- module_exit: driver exit entry point which will be called during the removal of module.
- x:
  
  function to be run at module insertion for module_init function.
  
  function to be run when driver is removed for module_exit function.
Here is an example of how to use the driver entry point API’s

module_init(myinitmodule);
module_exit(myexitmodule);

Example 1: Parking and unparking between threads

In this example let’s see how to park and unpark between threads and execute it.

List of headers

Include the follow header files(.h) to refer the API being used for the execution.

#include <linux/kernel.h>
#include <linux/kthread.h>
#include <linux/module.h>
#include <linux/delay.h>
#include <linux/init.h>

Module macros

Add the following module macros to display information about the license, author and description about the module.

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Linux Usr");
MODULE_DESCRIPTION("Example of kthread_park");

Initialize thread variables

Declare the thread variables which we are going to create and use in this example

static struct task_struct *thread1;
static struct task_struct *thread2;

Module init function

Add the module init function which will be executed once we load the kernel module using insmod command.

static int __init kthread_park_init(void)
{
    pr_info("Inside kthread init function\n");
    thread_start();
    return 0;
}

Thread start function

Add the thread start function which is called from module init function, creates the thread and starts it’s execution.

void thread_start(void)
{
    thread1 = kthread_run(thread_func_1,NULL,"kthread_park thread1 example");
    if (IS_ERR(thread1))
        pr_info("error creating thread1\n");
    else
        pr_info("thread1 created successfully\n");
    thread2 = kthread_run(thread_func_2,NULL,"kthread_park thread2 example");
    if(IS_ERR(thread2))
        pr_info("error creating thread2\n");
    else
        pr_info("thread2 created successfully\n");
}

Module exit function

Add the module exit function which will be executed once we unload the kernel module using rmmod command.

static void __exit kthread_park_exit(void)
{
    pr_info("Inside kthread exit function\n");
    thread_stop();
}

Thread stop function

Add the thread stop function which is called from module exit function, destroys the thread created and stops it’s execution.

void thread_stop(void)
{
    kthread_stop(thread2);
    kthread_stop(thread1);
    pr_info("Destroyed thread\n");
}

Thread function API

Add the thread function API which will be called as soon as the kthread is created and is in running state.

int thread_func_1(void *data)
{
    msleep(500);
    while(!kthread_should_stop()){
        if(kthread_should_park()) {
            kthread_parkme();
            pr_info("Thread 1 execution\n");
        }
        msleep(1000);
    }
    return 0;
}

int thread_func_2(void *data)
{
    kthread_park(thread1);
    while (!kthread_should_stop()) {
        pr_info("Thread 2 execution\n");
        msleep(1000);
    }
    kthread_unpark(thread1);
    return 0;
}

Driver entry points

Add the driver entry points which will be executed once the module is inserted or removed from the kernel.

module_init(kthread_park_init);
module_exit(kthread_park_exit);

See the full program below

kthread.c

#include <linux/kernel.h>
#include <linux/kthread.h>
#include <linux/module.h>
#include <linux/delay.h>
#include <linux/init.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Linux Usr");
MODULE_DESCRIPTION("Example of kthread_park");

static struct task_struct *thread1;
static struct task_struct *thread2;

/* thread_func_1 - executes when thread1 is created,
 * thread will parked,
 * once unparked prints a message and sleeps for 1000ms,
 * exits when kthread_stop is called */

int thread_func_1(void *data)
{
    msleep(500);
    while(!kthread_should_stop()){
        if(kthread_should_park()) {
            kthread_parkme();
            pr_info("Thread 1 execution\n");
        }
        msleep(1000);
    }
    return 0;
}

/*thread_func_2 - executes when thread2 is created,
 * will print a message and sleeps for 1000ms,
 * unparks thread1,
 * exits when kthread_stop is called */

int thread_func_2(void *data)
{
    kthread_park(thread1);
    while (!kthread_should_stop()) {
        pr_info("Thread 2 execution\n");
        msleep(1000);
    }
    kthread_unpark(thread1);
    return 0;
}

/* thread_start - creates thread and starts execution */

void thread_start(void)
{
    thread1 = kthread_run(thread_func_1,NULL,"kthread_park thread1 example");
    if (IS_ERR(thread1))
        pr_info("error creating thread1\n");
    else
        pr_info("thread1 created successfully\n");
    thread2 = kthread_run(thread_func_2,NULL,"kthread_park thread2 example");
    if(IS_ERR(thread2))
        pr_info("error creating thread2\n");
    else
        pr_info("thread2 created successfully\n");
}

/* kthread_park_init - calls thread_start,
 * executes when the module is loaded */

static int __init kthread_park_init(void)
{
    pr_info("Inside kthread init function\n");
    thread_start();
    return 0;
}

/* thread_stop - destroys thread and stops execution */

void thread_stop(void)
{
    kthread_stop(thread2);
    kthread_stop(thread1);
    pr_info("destroyed thread\n");
}

/* kthread_park_exit - calls thread_stop,
 * executes when module is unloaded */

static void __exit kthread_park_exit(void)
{
    pr_info("Inside kthread exit function\n");
    thread_stop();
}

module_init(kthread_park_init);
module_exit(kthread_park_exit);

Makefile

obj-m += kthread.o

all:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules 

clean:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean

Compile and load the module

Run make to compile the kernel source and generate the .ko image.

make -C /lib/modules/6.7.9/build M=$HOME/kthread_examples/
make[1]: Entering directory '/usr/src/linux-headers-6.7.9'
warning: the compiler differs from the one used to build the kernel
The kernel was built by: x86_64-linux-gnu-gcc (Ubuntu 12.2.0-3ubuntu1) 12.2.0
You are using:           gcc (Ubuntu 12.2.0-3ubuntu1) 12.2.0
CC [M]  $HOME/kthread_examples/kthread.o
MODPOST $HOME/kthread_examples/Module.symvers
CC [M]  $HOME/kthread_examples/kthread.mod.o
LD [M]  $HOME/kthread_examples/kthread.ko
BTF [M] $HOME/kthread_examples/kthread.ko
Skipping BTF generation for $HOME/kthread_examples/kthread.ko due to unavailability of vmlinux
make[1]: Leaving directory '/usr/src/linux-headers-6.7.9'

Check if the .ko is generated or not using ls command.

test@test-V520-15IKL:~$ ls -l
total 360
-rw-rw-r-- 1 test test    713 Mar 18 16:06 kthread.c
-rw-rw-r-- 1 test test 169784 Mar 18 16:08 kthread.ko
-rw-rw-r-- 1 test test     58 Mar 18 16:08 kthread.mod
-rw-rw-r-- 1 test test   1047 Mar 18 16:08 kthread.mod.c
-rw-rw-r-- 1 test test  96512 Mar 18 16:08 kthread.mod.o
-rw-rw-r-- 1 test test  74696 Mar 18 16:08 kthread.o
-rw-rw-r-- 1 test test    161 Mar 18 16:00 Makefile
-rw-rw-r-- 1 test test     58 Mar 18 16:08 modules.order
-rw-rw-r-- 1 test test      0 Mar 18 16:08 Module.symvers

Run modinfo command to get the information about the kernel module.

test@test-V520-15IKL:~/.../tc_1$ modinfo kthread.ko
filename:       $HOME/kthread_examples/kthread.ko
description:    Example of kthread_park
author:         Linux Usr
license:        GPL
srcversion:     8D2147F67AB01CF0E482DAC
depends:
retpoline:      Y
name:           kthread
vermagic:       6.7.9 SMP preempt mod_unload modversions

insert the module using insmod command.

test@test-V520-15IKL:~$ sudo insmod ./kthread.ko

check if the module is loaded or not using lsmod command.

test@test-V520-15IKL:~$ sudo lsmod | grep kthread
kthread                16384  0

check if the thread is created or not using ps command.

test@test-V520-15IKL:~$ ps -N | grep kthread_park

4097 ?        00:00:00 kthread_park thread1 example
4098 ?        00:00:00 kthread_park thread2 example

check for the kernel messages from init function and thread function once the module is loaded and thread is created.

test@test-V520-15IKL:~$ sudo dmesg
[  139.580438] Inside kthread init function
[  139.580462] thread1 created successfully
[  139.580474] thread2 created successfully
[  140.104929] Thread 2 execution
[  141.128291] Thread 2 execution
[  142.151620] Thread 2 execution

remove the module from kernel using rmmod command.

test@test-V520-15IKL:~$ sudo rmmod kthread

check if the module is still loaded after removing the kernel module using lsmod if it is not displayed in lsmod output it is verified that the module is removed successfully.

test@test-V520-15IKL:~$ sudo lsmod | grep kthread
test@test-V520-15IKL:~$

check if the thread is destroyed using ps command if it is not displayed in ps output we can confirm that the thread is destroyed successfully.

test@test-V520-15IKL:~$ ps -N | grep kthread_park
test@test-V520-15IKL:~$

Check for kernel messages from exit function using dmesg command.

test@test-V520-15IKL:~$ sudo dmesg
[  148.144187] Inside kthread exit function
[  148.280032] Thread 1 execution
[  149.315331] destroyed thread

Summary of Kthread APIs

kthread API	Learning
kthread_run	Create and wake a thread
kthread_park	Park a thread
kthread_unpark	Unpark a thread
kthread_parkme	Set the state of thread to TASK_PARKED
kthread_should_park	To determine whether the thread should be parked or not now
kthread_should_stop	To determine when thread should exit
kthread_stop	Stop a thread created by kthread_create

Summary of miscellaneous APIs

API	Learning
MODULE_LICENSE	Used to denote the license used in the kernel module
MODULE_AUTHOR	Used to mention the author of the kernel module
MODULE_DESCRIPTION	Used to describe what the module does
IS_ERR	Detects an error pointer
wake_up_process	wake up a specific process
msleep	will put in sleep for a certain amount of msecs time.
module_init	Driver initialization entry point
module_exit	Driver exit entry point
pr_info	Print an info-level message