what does "static int function(...) __acquires(..) __releases(...){" mean?

Question

I recently got a snippet of code in Linux kernel:

static int
fb_mmap(struct file *file, struct vm_area_struct * vma)
__acquires(&info->lock)
__releases(&info->lock)
{
...
}

What confused me is the two __functions following static int fb_mmap() right before "{",

a).What is the purpose of the two __funtions?

b).Why in that position?

c).Why do they have the prefix "__"?

d).Are there other examples similar to this?

Answer 1

Not everything ending with a pair of parenthesis is a function (call). In this case they are parameterized macro expansions. The macros are defined as

#define __acquires(x)  __attribute__((context(x,0,1)))
#define __releases(x)  __attribute__((context(x,1,0)))

in file include/linux/compiler.h in the kernel build tree.

The purpose of those macros expanding into attribute definitions is to annotate the function symbols with information about which locking structures the function will acquire (i.e. lock) and release (i.e. unlock). The purpose of those in particular is debugging locking mechanisms (the Linux kernel contains some code that allows it to detect potential deadlock situations and report on this).

https://en.wikipedia.org/wiki/Sparse

__attribute__ is a keyword specific to the GCC compiler, that allows to assign, well, attributes to a given symbol http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#Function-Attributes

Since macros are expanded at the text level, before the compiler is even looking at it, the result for your particular snippet, that the actual compilers sees would be

static int
fb_mmap(struct file *file, struct vm_area_struct * vma)
__attribute__((context(&info->lock,0,1)))
__attribute__((context(&info->lock,1,0)))
{
…
}

Those macros start with a double underscore __ to indicate, that they are part of the compiler environment. All identifiers starting with one or two underscores are reserved for the compiler environment implementation. In the case of the Linux kernel, because Linux is a operating system kernel that does not (because it simply is not availible) use the standard library, it's natural for it, do define it's own compiler environment definitions, private to it. Hence the two underscores to indicate, that this is compiler environment/implementation specific stuff.

Answer 2

They're probably macros defined with #define. You should look for the definition of such macros and see what they expand to. They might expand to some pragma giving hints to the compiler; they might expand to nothing giving hints to the developers or some analysis tool. The meaning might vary

Answer 3

The __attribute__ these macros evaluate to are compiler-specific features. man gcc explains some of the uses.

The prefix __ typically is used to avoid name clashes; double underscore as prefix and postfix mark an identifier as being used by the compiler itself.

More on gcc attributes can be found here.

More on the kernel use of these can be found here.