CodyChan CodyChan - 4 months ago 10
Linux Question

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

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 __funtions following
static int fb_mmap()
right before
"{"
,

a).
What are 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

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.