IO Wait Event

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 waitqueue?

What are the different ways to add waitqueue entries to waitqueue head?

How to wakeup the waiting threads once the task is completed?

How to use Kthread APIs ?

How to use Waitqueue 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_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 Waitqueue APIs

DECLARE_WAIT_QUEUE_HEAD

Here is the prototype of the API: DECLARE_WAIT_QUEUE_HEAD

# include <linux/wait.h>

#define DECLARE_WAIT_QUEUE_HEAD(name) \
        struct wait_queue_head name = __WAIT_QUEUE_HEAD_INITIALIZER(name)

where
- DECLARE_WAIT_QUEUE_HEAD : To declare and initialize wait queue head.
- name : name which is given to the wait queue head on declaration.
Here is the example of the API,

DECLARE_WAIT_QUEUE_HEAD(mywaitqueue);

io_wait_event

Here is the prototype of the API: io_wait_event

#include <linux/wait.h>

#define io_wait_event(wq_head, condition)

where
- io_wait_event : sleep until a condition gets true like wait_event() but with io_schedule()
- wq_head: the waitqueue to wait on
- condition: a C expression for the event to wait for
Here is an example of the API

io_wait_event(mywq_head, i<10);

wake_up

Here is the prototype of the API: wake_up

# include <linux/wait.h>

#define wake_up(x)                  __wake_up(x, TASK_NORMAL, 1, NULL)

where
- wake_up : wake up the waiting waitqueues under wait_event
- x: waitqueue which needs to be woken up.

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);

Summary of Kthread APIs

kthread API	Learning
kthread_run	Create and wake a thread
kthread_should_stop	To determine when thread should exit
kthread_stop	Stop a thread created by kthread_create

Summary of Waitqueue APIs

Waitqueue API	Learning
DECLARE_WAIT_QUEUE_HEAD	Declare waitqueue head
io_wait_event	sleeps until the condition is true
wake_up	wake up the waiting waitqueues under wait_event APIs

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