A Linux kernel module for stopping the system for a while
Tags: linux, kernel, stop, hang
Published: 2019-09-05 13:49:09

---
title: A Linux kernel module for stopping the system for a while
published: true
description: A brief explanation of a Linux kernel module for stopping the system for a while
tags: Linux, kernel, stop, hang
---

# Preface

This article introduces `stop-machine` Linux kernel module. It's used for stopping the system for a while. It's an [open-source software](https://github.com/satoru-takeuchi/stop-machine) and its usage is written in its `README.md` file. 

`stop-machine` module stops the whole system for five seconds.  Here `stop` means not only all processes can not run, but also all kernel functions can not run. 
 All kernel functions include device drivers and the corresponding interrupt handlers. So all storage I/Os and network I/Os stops from the perspective of users. User interface devices like keyboards and mouses can not work too.

Please note that it's very difficult to emulate the stopping of the whole system by userspace programs.

# Use case

This module can be used to confirm whether the system is tolerant to surprise freeze. It's far convenient than resetting the machine. 

You can change the stopping time in milliseconds by modifying [`STOP_MSECS` value](https://github.com/satoru-takeuchi/stop-machine/blob/master/stop-machine.c#L9).
For example, if you modify this value, by default 5000, to 60000, this module stops the whole system for one minute.

# Confirm the effect of this module

Let confirms whether this module can stop the whole system. First, please open a terminal emulator that is different from the one for loading this module. Then issue the following command to print the current time once a second at the former terminal emulator.

```console
$ for ((;;)) ; do sleep 1 ; date -R ; done
Sat, 04 May 2019 09:40:27 +0900
Sat, 04 May 2019 09:40:28 +0900
Sat, 04 May 2019 09:40:29 +0900
Sat, 04 May 2019 09:40:30 +0900
Sat, 04 May 2019 09:40:31 +0900
...
```

Then load this module at the latter terminal emulator.

```
$ sudo insmod stop-machine.ko
$　　　　　　　　　　　　　　　　　# You can see this prompt after five seconds 
```

Before showing the prompt, your inputs are ignored and the display looks freeze. However, after that, the system works as usual.

Then back to the former terminal emulator. You can see the message was skipped five times after loading this module. It's between (1) and (2) in the following output.

```console
...
Sat, 04 May 2019 09:44:38 +0900
Sat, 04 May 2019 09:44:39 +0900
Sat, 04 May 2019 09:44:40 +0900
Sat, 04 May 2019 09:44:41 +0900
Sat, 04 May 2019 09:44:42 +0900
Sat, 04 May 2019 09:44:43 +0900
Sat, 04 May 2019 09:44:44 +0900 # ... (1)
Sat, 04 May 2019 09:44:49 +0900 # ... (2)
Sat, 04 May 2019 09:44:50 +0900
Sat, 04 May 2019 09:44:51 +0900
...
```

At the last, unload this module as follows and close the two terminal emulators.

```
$ sudo rmmod stop-machine
$ 
```

# How this module is implemented

This module uses a kernel function called `stop_machine().` The spec of this function is as follows.

- Run the handler given by the caller, with stopping all the kernel,  userspace processes, and hardware interrupts.
- The first argument is the above-mentioned handler.
- The second argument is passed to the handler when it's called.
- The third argument means which CPUs should be stopped. Set NULL here means this function stops all available CPUs.

This function is originally for running very important functions without interrupted by any other functions. CPU hotplug feature is one of the users of this function.

In `stop-machine` module, the handler of `stop_machine()` wastes CPU time for five seconds. It's easy!

If you're interested in the implementation of `stop_machine(),` please refer to the Linux kernel's  source code. The definition is in `include/linux/stop_machine.h` and the implementation is in `kernel/stop_machine.c.`