Sparse annotations in libX11 and extensions

[Josh Triplett]

Jamey Sharp wrote:
> On Sun, Oct 15, 2006 at 10:22:45AM +0100, Magnus Kessler wrote:
>> you mentioned a few days ago on the XCB list that 'sparse' annotations would 
>> be useful to identify more of the locking issues in libX11 and the 
>> extensions. Can you please point me to some more information about sparse? 
>> I know where to get it from, but I haven't found much in terms of using it.
> 
> The best resource I have on this subject is named Josh Triplett. ;-)
> Josh, is there anything better than reading sparse source for learning
> how to apply locking annotations?

Well, one thing slightly better: see my test case validation/context.c
in the sparse tree for specific examples of acquire and release
functions and test cases for what the sparse annotations can check.

The raw sparse annotations for locking look like this, on a function
prototype:

some_type_t some_func(func_signature)
__attribute__((context(lock_expression,in_context,out_context)));

This states that the context lock_expression should have value
in_context on entry, and out_context on exit.

In a macro, you can use the similar __context__ statement:

__context__(lock_expression,change_by);

This just changes the given context by the given delta (positive or
negative).

In both expressions, you can omit lock_expression to use the generic
global context.  Since sparse currently parses but ignores
lock_expression, you'll get the same effect either way, but if an
obvious lock expression to pass exists, use it to allow for future
intelligent handling by sparse.

> Are sparse annotations expressive enough to handle a statement like
> this? "This function requires the display lock to be held on entry. If
> it returns -1, then it has released the display lock, else the display
> lock is still held." libXi has a function with that contract. :-(

Not quite.  Linux has a similar situation with functions like
spin_trylock.  In that case, it uses the following mechanism:

# define __cond_lock(x,c)       ((c) ? ({ __acquire(x); 1; }) : 0)
...
#define spin_trylock(lock)              __cond_lock(_spin_trylock(lock))

(where __acquire(x) in turn just does __context__(x,1)).  Because of the
way sparse does constant folding in boolean expressions, this mechanism
means that if you use a macro like spin_trylock in an if condition, the
context change will only occur down the appropriate branch of the if.

> Anyway, I'd suggest that further discussion happen on either the xcb or
> xorg list. More people will probably be interested in finding these bugs
> quickly. :-)

Lists CCed.

- Josh Triplett


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
URL: <http://lists.x.org/archives/xorg/attachments/20061017/73ee81c4/attachment.pgp>