[lttng-dev] [rp] [RFC PATCH urcu] Document uatomic operations

[Josh Triplett]

On Wed, May 16, 2012 at 11:32:38AM -0700, Paul E. McKenney wrote:
> On Wed, May 16, 2012 at 02:17:42PM -0400, Mathieu Desnoyers wrote:
> > * Paul E. McKenney (paulmck at linux.vnet.ibm.com) wrote:
> > > On Tue, May 15, 2012 at 08:10:03AM -0400, Mathieu Desnoyers wrote:
> > > > * Paul E. McKenney (paulmck at linux.vnet.ibm.com) wrote:
> > > > > On Mon, May 14, 2012 at 10:39:01PM -0400, Mathieu Desnoyers wrote:
> > > > > > Document each atomic operation provided by urcu/uatomic.h, along with
> > > > > > their memory barrier guarantees.
> > > > > 
> > > > > Great to see the documentation!!!  Some comments below.
> > > > > 
> > > > > 							Thanx, Paul
> > > > > 
> > > > > > Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
> > > > > > ---
> > > > > > diff --git a/doc/Makefile.am b/doc/Makefile.am
> > > > > > index bec1d7c..db9811c 100644
> > > > > > --- a/doc/Makefile.am
> > > > > > +++ b/doc/Makefile.am
> > > > > > @@ -1 +1 @@
> > > > > > -dist_doc_DATA = rcu-api.txt
> > > > > > +dist_doc_DATA = rcu-api.txt uatomic-api.txt
> > > > > > diff --git a/doc/uatomic-api.txt b/doc/uatomic-api.txt
> > > > > > new file mode 100644
> > > > > > index 0000000..3605acf
> > > > > > --- /dev/null
> > > > > > +++ b/doc/uatomic-api.txt
> > > > > > @@ -0,0 +1,80 @@
> > > > > > +Userspace RCU Atomic Operations API
> > > > > > +by Mathieu Desnoyers and Paul E. McKenney
> > > > > > +
> > > > > > +
> > > > > > +This document describes the <urcu/uatomic.h> API. Those are the atomic
> > > > > > +operations provided by the Userspace RCU library. The general rule
> > > > > > +regarding memory barriers is that only uatomic_xchg(),
> > > > > > +uatomic_cmpxchg(), uatomic_add_return(), and uatomic_sub_return() imply
> > > > > > +full memory barriers before and after the atomic operation. Other
> > > > > > +primitives don't guarantee any memory barrier.
> > > > > > +
> > > > > > +Only atomic operations performed on integers ("int" and "long", signed
> > > > > > +and unsigned) are supported on all architectures. Some architectures
> > > > > > +also support 1-byte and 2-byte atomic operations. Those respectively
> > > > > > +have UATOMIC_HAS_ATOMIC_BYTE and UATOMIC_HAS_ATOMIC_SHORT defined when
> > > > > > +uatomic.h is included. An architecture trying to perform an atomic write
> > > > > > +to a type size not supported by the architecture will trigger an illegal
> > > > > > +instruction.
> > > > > > +
> > > > > > +In the description below, "type" is a type that can be atomically
> > > > > > +written to by the architecture. It needs to be at most word-sized, and
> > > > > > +its alignment needs to greater or equal to its size.
> > > > > > +
> > > > > > +type uatomic_set(type *addr, type v)
> > > > > > +
> > > > > > +	Atomically write @v into @addr.
> > > > > 
> > > > > Wouldn't this instead be "void uatomic_set(type *addr, type v)"?
> > > > 
> > > > Well, in that case, we'd need to change the macro. Currently,
> > > > _uatomic_set maps directly to:
> > > > 
> > > > #define _uatomic_set(addr, v)   CMM_STORE_SHARED(*(addr), (v))
> > > > 
> > > > and CMM_STORE_SHARED returns v. The question becomes: should we change
> > > > _uatomic_set or CMM_STORE_SHARED so they don't return anything, or
> > > > document that they return something ?
> > > > 
> > > > One thing I noticed is that linters often complain that the return value
> > > > of CMM_STORE_SHARED is never used. One thing we could look into is to
> > > > try some gcc attributes and/or linter annotations to flag this return
> > > > value as possibly unused. Thoughts ?
> > > 
> > > Hmmm...
> > > 
> > > Does the following work?
> > > 
> > > #define _uatomic_set(addr, v)   ((void)CMM_STORE_SHARED(*(addr), (v)))
> > 
> > Well, it would work, yes, but then we would not be consistent between
> > return values or no return values of:
> > 
> > uatomic_set()
> > rcu_assign_pointer()
> > rcu_set_pointer()
> > 
> > if you notice, in the Linux kernel, rcu_assign_pointer returns the
> > new pointer value. But you are right that atomic_set() does not return
> > anything. So which consistency would be best to keep ?
> 
> Hmmm...  I wonder how many people actually use rcu_assign_pointer()'s
> return value?  If no one, I should make it a do-while(0).  Although
> cscope does not show anything, I should probably put together a
> coccinelle script.

I just searched the entire Linux kernel with git grep
'\S.*rcu_assign_pointer' (any non-whitespace preceding
rcu_assign_pointer), and found no instances of anything assuming a
return value from rcu_assign_pointer.  I'd recommend making it void.

- Josh Triplett