linux-imx

PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()

​

Most of the time, you can use values from rcu_dereference() or one of

the similar primitives without worries.  Dereferencing (prefix "*"),

field selection ("->"), assignment ("="), address-of ("&"), addition and

subtraction of constants, and casts all work quite naturally and safely.

​

It is nevertheless possible to get into trouble with other operations.

Follow these rules to keep your RCU code working properly:

​

o   You must use one of the rcu_dereference() family of primitives

    to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU

    will complain.  Worse yet, your code can see random memory-corruption

    bugs due to games that compilers and DEC Alpha can play.

    Without one of the rcu_dereference() primitives, compilers

    can reload the value, and won't your code have fun with two

    different values for a single pointer!  Without rcu_dereference(),

    DEC Alpha can load a pointer, dereference that pointer, and

    return data preceding initialization that preceded the store of

    the pointer.

​

    In addition, the volatile cast in rcu_dereference() prevents the

    compiler from deducing the resulting pointer value.  Please see

    the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"

    for an example where the compiler can in fact deduce the exact

    value of the pointer, and thus cause misordering.

​

o   You are only permitted to use rcu_dereference on pointer values.

    The compiler simply knows too much about integral values to

    trust it to carry dependencies through integer operations.

    There are a very few exceptions, namely that you can temporarily

    cast the pointer to uintptr_t in order to:

​

    o   Set bits and clear bits down in the must-be-zero low-order

        bits of that pointer.  This clearly means that the pointer

        must have alignment constraints, for example, this does

        -not- work in general for char* pointers.

​

    o   XOR bits to translate pointers, as is done in some

        classic buddy-allocator algorithms.

​

    It is important to cast the value back to pointer before

    doing much of anything else with it.

​

o   Avoid cancellation when using the "+" and "-" infix arithmetic

    operators.  For example, for a given variable "x", avoid

    "(x-(uintptr_t)x)" for char* pointers.  The compiler is within its

    rights to substitute zero for this sort of expression, so that

    subsequent accesses no longer depend on the rcu_dereference(),

    again possibly resulting in bugs due to misordering.

​

    Of course, if "p" is a pointer from rcu_dereference(), and "a"

    and "b" are integers that happen to be equal, the expression

    "p+a-b" is safe because its value still necessarily depends on

    the rcu_dereference(), thus maintaining proper ordering.

​

o   If you are using RCU to protect JITed functions, so that the

    "()" function-invocation operator is applied to a value obtained

    (directly or indirectly) from rcu_dereference(), you may need to

    interact directly with the hardware to flush instruction caches.

    This issue arises on some systems when a newly JITed function is

    using the same memory that was used by an earlier JITed function.

​

o   Do not use the results from relational operators ("==", "!=",

    ">", ">=", "<", or "<=") when dereferencing.  For example,

    the following (quite strange) code is buggy:

​

        int *p;

        int *q;

​

        ...

​

        p = rcu_dereference(gp)

        q = &global_q;

        q += p > &oom_p;

        r1 = *q;  /* BUGGY!!! */

​

    As before, the reason this is buggy is that relational operators

    are often compiled using branches.  And as before, although

    weak-memory machines such as ARM or PowerPC do order stores

    after such branches, but can speculate loads, which can again

    result in misordering bugs.

​

o   Be very careful about comparing pointers obtained from

    rcu_dereference() against non-NULL values.  As Linus Torvalds

    explained, if the two pointers are equal, the compiler could

    substitute the pointer you are comparing against for the pointer

    obtained from rcu_dereference().  For example:

​

        p = rcu_dereference(gp);

        if (p == &default_struct)

            do_default(p->a);