linux kernel

Mutex guards in the Linux kernel

Posted by Marcus Folkesson on Friday, December 1, 2023

Mutex guards in the Linux kernel

I found an interresting thread [1] while searching my inbox for something completely unrelated.

Peter Zijistra has written a few cleanup functions that where introduced in v6.4 with this commit:

commit 54da6a0924311c7cf5015533991e44fb8eb12773
Author: Peter Zijlstra <peterz@infradead.org>
Date:   Fri May 26 12:23:48 2023 +0200

    locking: Introduce __cleanup() based infrastructure

    Use __attribute__((__cleanup__(func))) to build:

     - simple auto-release pointers using __free()

     - 'classes' with constructor and destructor semantics for
       scope-based resource management.

     - lock guards based on the above classes.

    Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>

It adds functionality to "guard" locks. The guard wraps the lock, takes ownership of the given mutex and release it as soon the guard leaves the scope. In other words - no more forgotten locks due to early exits.

Compare this to the std::lock_guard class we have in C++.

Although this adds valuable functionality to the core, it's currently not widely used. In fact, it only has two users in the latest (v.6.6) kernel:

1	$ git grep -l "guard(mutex)" 
2	drivers/gpio/gpio-sim.c
3	kernel/sched/core.c

Hands on

I have adapted ( [2], [3]) two of my drivers to make use of the guard locks. The adaptation is quickly made.

The features is located in linux/cleanup.h:

1+#include <linux/cleanup.h>

Then we can start to make use of the guards. What I like is that the code will be simplier in two ways:

  • All the mutex_lock-pairs in the same scope could be replaced with guard(mutex)(&your->mutex).
  • The code can now return without taking any taken locks into account.

Together with device managed ( devm ) resources, you will end up with a code that clean up itself pretty good.

A typical adaption to guarded mutexes could look likt this:

 1	@@ -83,31 +85,26 @@ static int pxrc_open(struct input_dev *input)
 2		struct pxrc *pxrc = input_get_drvdata(input);
 3		int retval;
 4
 5	-       mutex_lock(&pxrc->pm_mutex);
 6	+       guard(mutex)(&pxrc->pm_mutex);
 7		retval = usb_submit_urb(pxrc->urb, GFP_KERNEL);
 8		if (retval) {
 9			dev_err(&pxrc->intf->dev,
10				"%s - usb_submit_urb failed, error: %d\n",
11				__func__, retval);
12	-               retval = -EIO;
13	-               goto out;
14	+               return -EIO;
15		}
16
17		pxrc->is_open = true;
18	-
19	-out:
20	-       mutex_unlock(&pxrc->pm_mutex);
21	-       return retval;
22	+       return 0;
23	 }

What it does is:

  • Removes the mutex_lock/mutex_unlock pair
  • Simplifies the error handling to just return in case of error
  • No need for the out: label anymore so remove it

Under the hood

The implementation makes use of the __attribute__((cleanup())) attribute that is available for both LLVM [4] and GCC [5].

Here is what the GCC documentation [5] says about the cleanup_function:

cleanup (cleanup_function)
The cleanup attribute runs a function when the variable goes out of scope. This attribute can only be applied to auto function scope variables; it may not be applied to parameters or variables with static storage duration.
The function must take one parameter, a pointer to a type compatible with the variable. The return value of the function (if any) is ignored.

If -fexceptions is enabled, then cleanup_function is run during the stack unwinding that happens during the processing of the exception.
Note that the cleanup attribute does not allow the exception to be caught, only to perform an action. It's undefined what happens if cleanup_function does not return normally.

To illustrate this, consider the following example:

 1#include <stdio.h>
 2
 3void cleanup_func (int *x)
 4{
 5	printf("Tidy up for x as it's leaving its scope\n");
 6}
 7
 8int main(int argc, char **argv)
 9{
10	printf("Start\n");
11	{
12		int x __attribute__((cleanup(cleanup_func)));
13		/* Do stuff */
14	}
15	printf("Exit\n");
16}

We create a variable, x, declared with the cleanup attribute inside of its own scope. This makes that the cleanup_func() will be called as soon x goes out of scope.

Here is the output of the example above: 

1$ gcc main.c -o main && ./main
2Start
3Tidy up for x as it's leaving its scope
4Exit

As you can see, the cleanup_func() is called in between of Start and Exit - as expected.

CATALOG
    FEATURED TAGS
    audio beer birds blacksmith booting buildroot camera clockwork cultivation debugging device drivers dnd docker git go ham home control hugo knives leatherwork libostree linux linux kernel network programming qemu radio swupdate systemd til tools v4l2 vim wireless yocto zephyr