€•6      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”(hhŒparent”hubaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ'/translations/zh_CN/RCU/rcu_dereference”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”(hhhh2ubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/zh_TW/RCU/rcu_dereference”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”(hhhhFubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/it_IT/RCU/rcu_dereference”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”(hhhhZubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/ja_JP/RCU/rcu_dereference”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”(hhhhnubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/ko_KR/RCU/rcu_dereference”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”(hhhh‚ubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/sp_SP/RCU/rcu_dereference”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒtarget”“”)”}”(hŒ.. _rcu_dereference_doc:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œrcu-dereference-doc”uh1h¡h KhhhžhhŸŒA/var/lib/git/docbuild/linux/Documentation/RCU/rcu_dereference.rst”ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ?PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()”h]”hŒ?PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()”…””}”(hh¹hh·hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhh²hžhhŸh¯h KubhŒ	paragraph”“”)”}”(hX  Proper care and feeding of address and data dependencies is critically
important to correct use of things like RCU.  To this end, the pointers
returned from the rcu_dereference() family of primitives carry address and
data dependencies.  These dependencies extend from the rcu_dereference()
macro's load of the pointer to the later use of that pointer to compute
either the address of a later memory access (representing an address
dependency) or the value written by a later memory access (representing
a data dependency).”h]”hX  Proper care and feeding of address and data dependencies is critically
important to correct use of things like RCU.  To this end, the pointers
returned from the rcu_dereference() family of primitives carry address and
data dependencies.  These dependencies extend from the rcu_dereference()
macroâ€™s load of the pointer to the later use of that pointer to compute
either the address of a later memory access (representing an address
dependency) or the value written by a later memory access (representing
a data dependency).”…””}”(hhÉhhÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhÆ)”}”(hXµ  Most of the time, these dependencies are preserved, permitting you to
freely use values from rcu_dereference().  For example, dereferencing
(prefix "*"), field selection ("->"), assignment ("="), address-of
("&"), casts, and addition or subtraction of constants all work quite
naturally and safely.  However, because current compilers do not take
either address or data dependencies into account it is still possible
to get into trouble.”h]”hXÅ  Most of the time, these dependencies are preserved, permitting you to
freely use values from rcu_dereference().  For example, dereferencing
(prefix â€œ*â€), field selection (â€œ->â€), assignment (â€œ=â€), address-of
(â€&â€), casts, and addition or subtraction of constants all work quite
naturally and safely.  However, because current compilers do not take
either address or data dependencies into account it is still possible
to get into trouble.”…””}”(hXµ  Most of the time, these dependencies are preserved, permitting you to
freely use values from rcu_dereference().  For example, dereferencing
(prefix "*"), field selection ("->"), assignment ("="), address-of
("&"), casts, and addition or subtraction of constants all work quite
naturally and safely.  However, because current compilers do not take
either address or data dependencies into account it is still possible
to get into trouble.”hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhÆ)”}”(hŒ¬Follow these rules to preserve the address and data dependencies emanating
from your calls to rcu_dereference() and friends, thus keeping your RCU
readers working properly:”h]”hŒ¬Follow these rules to preserve the address and data dependencies emanating
from your calls to rcu_dereference() and friends, thus keeping your RCU
readers working properly:”…””}”(hhæhhähžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khh²hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hXÖ  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.  (As noted later, in recent kernels READ_ONCE()
also prevents DEC Alpha from playing these tricks.)

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.
”h]”(hÆ)”}”(hX¡  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.  (As noted later, in recent kernels READ_ONCE()
also prevents DEC Alpha from playing these tricks.)”h]”hX£  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.  (As noted later, in recent kernels READ_ONCE()
also prevents DEC Alpha from playing these tricks.)”…””}”(hhÿhhýhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KhhùubhÆ)”}”(hX2  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.”h]”hX6  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.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K'hhùubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubhø)”}”(hX  In the special case where data is added but is never removed
while readers are accessing the structure, READ_ONCE() may be used
instead of rcu_dereference().  In this case, use of READ_ONCE()
takes on the role of the lockless_dereference() primitive that
was removed in v4.15.
”h]”hÆ)”}”(hX  In the special case where data is added but is never removed
while readers are accessing the structure, READ_ONCE() may be used
instead of rcu_dereference().  In this case, use of READ_ONCE()
takes on the role of the lockless_dereference() primitive that
was removed in v4.15.”h]”hX  In the special case where data is added but is never removed
while readers are accessing the structure, READ_ONCE() may be used
instead of rcu_dereference().  In this case, use of READ_ONCE()
takes on the role of the lockless_dereference() primitive that
was removed in v4.15.”…””}”(hj%  hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K-hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubhø)”}”(hXæ  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:

-       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.

-       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.
”h]”(hÆ)”}”(hX%  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:”h]”hX%  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:”…””}”(hj=  hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K3hj7  ubhó)”}”(hhh]”(hø)”}”(hŒØ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.
”h]”hÆ)”}”(hŒ×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.”h]”(hŒ®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
”…””}”(hŒ®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
”hjP  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*not*”h]”hŒnot”…””}”(hhhj[  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hjP  ubhŒ$ work in general for char* pointers.”…””}”(hŒ$ work in general for char* pointers.”hjP  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K9hjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjI  ubhø)”}”(hŒWXOR bits to translate pointers, as is done in some
classic buddy-allocator algorithms.
”h]”hÆ)”}”(hŒVXOR bits to translate pointers, as is done in some
classic buddy-allocator algorithms.”h]”hŒVXOR bits to translate pointers, as is done in some
classic buddy-allocator algorithms.”…””}”(hj€  hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K>hjz  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjI  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1hòhŸh¯h K9hj7  ubhÆ)”}”(hŒ]It is important to cast the value back to pointer before
doing much of anything else with it.”h]”hŒ]It is important to cast the value back to pointer before
doing much of anything else with it.”…””}”(hjœ  hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KAhj7  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubhø)”}”(hXc  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.
”h]”(hÆ)”}”(hXm  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.”h]”hX}  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.”…””}”(hj´  hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KDhj®  ubhÆ)”}”(hŒó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.”h]”hX  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.”…””}”(hjÂ  hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KKhj®  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubhø)”}”(hXƒ  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.
”h]”hÆ)”}”(hX‚  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.”h]”hX†  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.”…””}”(hjÚ  hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KPhjÔ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubhø)”}”(hX[  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.
”h]”(hÆ)”}”(hŒ¦Do not use the results from relational operators ("==", "!=",
">", ">=", "<", or "<=") when dereferencing.  For example,
the following (quite strange) code is buggy::”h]”hŒ½Do not use the results from relational operators (â€œ==â€, â€œ!=â€,
â€œ>â€, â€œ>=â€, â€œ<â€, or â€œ<=â€) when dereferencing.  For example,
the following (quite strange) code is buggy:”…””}”(hŒ¥Do not use the results from relational operators ("==", "!=",
">", ">=", "<", or "<=") when dereferencing.  For example,
the following (quite strange) code is buggy:”hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KWhjì  ubhŒliteral_block”“”)”}”(hŒfint *p;
int *q;

...

p = rcu_dereference(gp)
q = &global_q;
q += p > &oom_p;
r1 = *q;  /* BUGGY!!! */”h]”hŒfint *p;
int *q;

...

p = rcu_dereference(gp)
q = &global_q;
q += p > &oom_p;
r1 = *q;  /* BUGGY!!! */”…””}”(hhhj  ubah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jÿ  hŸh¯h K[hjì  ubhÆ)”}”(hX  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.”h]”hX  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.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kehjì  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubhø)”}”(hXÚ  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);

Because the compiler now knows that the value of "p" is exactly
the address of the variable "default_struct", it is free to
transform this code into the following::

        p = rcu_dereference(gp);
        if (p == &default_struct)
                do_default(default_struct.a);

On ARM and Power hardware, the load from "default_struct.a"
can now be speculated, such that it might happen before the
rcu_dereference().  This could result in bugs due to misordering.

However, comparisons are OK in the following cases:

-       The comparison was against the NULL pointer.  If the
        compiler knows that the pointer is NULL, you had better
        not be dereferencing it anyway.  If the comparison is
        non-equal, the compiler is none the wiser.  Therefore,
        it is safe to compare pointers from rcu_dereference()
        against NULL pointers.

-       The pointer is never dereferenced after being compared.
        Since there are no subsequent dereferences, the compiler
        cannot use anything it learned from the comparison
        to reorder the non-existent subsequent dereferences.
        This sort of comparison occurs frequently when scanning
        RCU-protected circular linked lists.

        Note that if the pointer comparison is done outside
        of an RCU read-side critical section, and the pointer
        is never dereferenced, rcu_access_pointer() should be
        used in place of rcu_dereference().  In most cases,
        it is best to avoid accidental dereferences by testing
        the rcu_access_pointer() return value directly, without
        assigning it to a variable.

        Within an RCU read-side critical section, there is little
        reason to use rcu_access_pointer().

-       The comparison is against a pointer that references memory
        that was initialized "a long time ago."  The reason
        this is safe is that even if misordering occurs, the
        misordering will not affect the accesses that follow
        the comparison.  So exactly how long ago is "a long
        time ago"?  Here are some possibilities:

        -       Compile time.

        -       Boot time.

        -       Module-init time for module code.

        -       Prior to kthread creation for kthread code.

        -       During some prior acquisition of the lock that
                we now hold.

        -       Before mod_timer() time for a timer handler.

        There are many other possibilities involving the Linux
        kernel's wide array of primitives that cause code to
        be invoked at a later time.

-       The pointer being compared against also came from
        rcu_dereference().  In this case, both pointers depend
        on one rcu_dereference() or another, so you get proper
        ordering either way.

        That said, this situation can make certain RCU usage
        bugs more likely to happen.  Which can be a good thing,
        at least if they happen during testing.  An example
        of such an RCU usage bug is shown in the section titled
        "EXAMPLE OF AMPLIFIED RCU-USAGE BUG".

-       All of the accesses following the comparison are stores,
        so that a control dependency preserves the needed ordering.
        That said, it is easy to get control dependencies wrong.
        Please see the "CONTROL DEPENDENCIES" section of
        Documentation/memory-barriers.txt for more details.

-       The pointers are not equal *and* the compiler does
        not have enough information to deduce the value of the
        pointer.  Note that the volatile cast in rcu_dereference()
        will normally prevent the compiler from knowing too much.

        However, please note that if the compiler knows that the
        pointer takes on only one of two values, a not-equal
        comparison will provide exactly the information that the
        compiler needs to deduce the value of the pointer.
”h]”(hÆ)”}”(hX"  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::”h]”hX!  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:”…””}”(hX!  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:”hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kkhj%  ubj   )”}”(hŒLp = rcu_dereference(gp);
if (p == &default_struct)
        do_default(p->a);”h]”hŒLp = rcu_dereference(gp);
if (p == &default_struct)
        do_default(p->a);”…””}”(hhhj8  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Kqhj%  ubhÆ)”}”(hŒ¤Because the compiler now knows that the value of "p" is exactly
the address of the variable "default_struct", it is free to
transform this code into the following::”h]”hŒ«Because the compiler now knows that the value of â€œpâ€ is exactly
the address of the variable â€œdefault_structâ€, it is free to
transform this code into the following:”…””}”(hŒ£Because the compiler now knows that the value of "p" is exactly
the address of the variable "default_struct", it is free to
transform this code into the following:”hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kuhj%  ubj   )”}”(hŒXp = rcu_dereference(gp);
if (p == &default_struct)
        do_default(default_struct.a);”h]”hŒXp = rcu_dereference(gp);
if (p == &default_struct)
        do_default(default_struct.a);”…””}”(hhhjU  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Kyhj%  ubhÆ)”}”(hŒ¹On ARM and Power hardware, the load from "default_struct.a"
can now be speculated, such that it might happen before the
rcu_dereference().  This could result in bugs due to misordering.”h]”hŒ½On ARM and Power hardware, the load from â€œdefault_struct.aâ€
can now be speculated, such that it might happen before the
rcu_dereference().  This could result in bugs due to misordering.”…””}”(hje  hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K}hj%  ubhÆ)”}”(hŒ3However, comparisons are OK in the following cases:”h]”hŒ3However, comparisons are OK in the following cases:”…””}”(hjs  hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Khj%  ubhó)”}”(hhh]”(hø)”}”(hX'  The comparison was against the NULL pointer.  If the
compiler knows that the pointer is NULL, you had better
not be dereferencing it anyway.  If the comparison is
non-equal, the compiler is none the wiser.  Therefore,
it is safe to compare pointers from rcu_dereference()
against NULL pointers.
”h]”hÆ)”}”(hX&  The comparison was against the NULL pointer.  If the
compiler knows that the pointer is NULL, you had better
not be dereferencing it anyway.  If the comparison is
non-equal, the compiler is none the wiser.  Therefore,
it is safe to compare pointers from rcu_dereference()
against NULL pointers.”h]”hX&  The comparison was against the NULL pointer.  If the
compiler knows that the pointer is NULL, you had better
not be dereferencing it anyway.  If the comparison is
non-equal, the compiler is none the wiser.  Therefore,
it is safe to compare pointers from rcu_dereference()
against NULL pointers.”…””}”(hjˆ  hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Kƒhj‚  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hj  ubhø)”}”(hXõ  The pointer is never dereferenced after being compared.
Since there are no subsequent dereferences, the compiler
cannot use anything it learned from the comparison
to reorder the non-existent subsequent dereferences.
This sort of comparison occurs frequently when scanning
RCU-protected circular linked lists.

Note that if the pointer comparison is done outside
of an RCU read-side critical section, and the pointer
is never dereferenced, rcu_access_pointer() should be
used in place of rcu_dereference().  In most cases,
it is best to avoid accidental dereferences by testing
the rcu_access_pointer() return value directly, without
assigning it to a variable.

Within an RCU read-side critical section, there is little
reason to use rcu_access_pointer().
”h]”(hÆ)”}”(hX5  The pointer is never dereferenced after being compared.
Since there are no subsequent dereferences, the compiler
cannot use anything it learned from the comparison
to reorder the non-existent subsequent dereferences.
This sort of comparison occurs frequently when scanning
RCU-protected circular linked lists.”h]”hX5  The pointer is never dereferenced after being compared.
Since there are no subsequent dereferences, the compiler
cannot use anything it learned from the comparison
to reorder the non-existent subsequent dereferences.
This sort of comparison occurs frequently when scanning
RCU-protected circular linked lists.”…””}”(hj   hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KŠhjš  ubhÆ)”}”(hX^  Note that if the pointer comparison is done outside
of an RCU read-side critical section, and the pointer
is never dereferenced, rcu_access_pointer() should be
used in place of rcu_dereference().  In most cases,
it is best to avoid accidental dereferences by testing
the rcu_access_pointer() return value directly, without
assigning it to a variable.”h]”hX^  Note that if the pointer comparison is done outside
of an RCU read-side critical section, and the pointer
is never dereferenced, rcu_access_pointer() should be
used in place of rcu_dereference().  In most cases,
it is best to avoid accidental dereferences by testing
the rcu_access_pointer() return value directly, without
assigning it to a variable.”…””}”(hj®  hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K‘hjš  ubhÆ)”}”(hŒ]Within an RCU read-side critical section, there is little
reason to use rcu_access_pointer().”h]”hŒ]Within an RCU read-side critical section, there is little
reason to use rcu_access_pointer().”…””}”(hj¼  hjº  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K™hjš  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hj  ubhø)”}”(hXÍ  The comparison is against a pointer that references memory
that was initialized "a long time ago."  The reason
this is safe is that even if misordering occurs, the
misordering will not affect the accesses that follow
the comparison.  So exactly how long ago is "a long
time ago"?  Here are some possibilities:

-       Compile time.

-       Boot time.

-       Module-init time for module code.

-       Prior to kthread creation for kthread code.

-       During some prior acquisition of the lock that
        we now hold.

-       Before mod_timer() time for a timer handler.

There are many other possibilities involving the Linux
kernel's wide array of primitives that cause code to
be invoked at a later time.
”h]”(hÆ)”}”(hX5  The comparison is against a pointer that references memory
that was initialized "a long time ago."  The reason
this is safe is that even if misordering occurs, the
misordering will not affect the accesses that follow
the comparison.  So exactly how long ago is "a long
time ago"?  Here are some possibilities:”h]”hX=  The comparison is against a pointer that references memory
that was initialized â€œa long time ago.â€  The reason
this is safe is that even if misordering occurs, the
misordering will not affect the accesses that follow
the comparison.  So exactly how long ago is â€œa long
time agoâ€?  Here are some possibilities:”…””}”(hjÔ  hjÒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KœhjÎ  ubhó)”}”(hhh]”(hø)”}”(hŒCompile time.
”h]”hÆ)”}”(hŒCompile time.”h]”hŒCompile time.”…””}”(hjé  hjç  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K£hjã  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjà  ubhø)”}”(hŒBoot time.
”h]”hÆ)”}”(hŒ
Boot time.”h]”hŒ
Boot time.”…””}”(hj  hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K¥hjû  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjà  ubhø)”}”(hŒ"Module-init time for module code.
”h]”hÆ)”}”(hŒ!Module-init time for module code.”h]”hŒ!Module-init time for module code.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K§hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjà  ubhø)”}”(hŒ,Prior to kthread creation for kthread code.
”h]”hÆ)”}”(hŒ+Prior to kthread creation for kthread code.”h]”hŒ+Prior to kthread creation for kthread code.”…””}”(hj1  hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K©hj+  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjà  ubhø)”}”(hŒ<During some prior acquisition of the lock that
we now hold.
”h]”hÆ)”}”(hŒ;During some prior acquisition of the lock that
we now hold.”h]”hŒ;During some prior acquisition of the lock that
we now hold.”…””}”(hjI  hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K«hjC  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjà  ubhø)”}”(hŒ-Before mod_timer() time for a timer handler.
”h]”hÆ)”}”(hŒ,Before mod_timer() time for a timer handler.”h]”hŒ,Before mod_timer() time for a timer handler.”…””}”(hja  hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K®hj[  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjà  ubeh}”(h]”h ]”h"]”h$]”h&]”j˜  j™  uh1hòhŸh¯h K£hjÎ  ubhÆ)”}”(hŒ‡There are many other possibilities involving the Linux
kernel's wide array of primitives that cause code to
be invoked at a later time.”h]”hŒ‰There are many other possibilities involving the Linux
kernelâ€™s wide array of primitives that cause code to
be invoked at a later time.”…””}”(hj{  hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K°hjÎ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hj  ubhø)”}”(hXµ  The pointer being compared against also came from
rcu_dereference().  In this case, both pointers depend
on one rcu_dereference() or another, so you get proper
ordering either way.

That said, this situation can make certain RCU usage
bugs more likely to happen.  Which can be a good thing,
at least if they happen during testing.  An example
of such an RCU usage bug is shown in the section titled
"EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
”h]”(hÆ)”}”(hŒ´The pointer being compared against also came from
rcu_dereference().  In this case, both pointers depend
on one rcu_dereference() or another, so you get proper
ordering either way.”h]”hŒ´The pointer being compared against also came from
rcu_dereference().  In this case, both pointers depend
on one rcu_dereference() or another, so you get proper
ordering either way.”…””}”(hj“  hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K´hj  ubhÆ)”}”(hŒþThat said, this situation can make certain RCU usage
bugs more likely to happen.  Which can be a good thing,
at least if they happen during testing.  An example
of such an RCU usage bug is shown in the section titled
"EXAMPLE OF AMPLIFIED RCU-USAGE BUG".”h]”hX  That said, this situation can make certain RCU usage
bugs more likely to happen.  Which can be a good thing,
at least if they happen during testing.  An example
of such an RCU usage bug is shown in the section titled
â€œEXAMPLE OF AMPLIFIED RCU-USAGE BUGâ€.”…””}”(hj¡  hjŸ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K¹hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hj  ubhø)”}”(hX  All of the accesses following the comparison are stores,
so that a control dependency preserves the needed ordering.
That said, it is easy to get control dependencies wrong.
Please see the "CONTROL DEPENDENCIES" section of
Documentation/memory-barriers.txt for more details.
”h]”hÆ)”}”(hX  All of the accesses following the comparison are stores,
so that a control dependency preserves the needed ordering.
That said, it is easy to get control dependencies wrong.
Please see the "CONTROL DEPENDENCIES" section of
Documentation/memory-barriers.txt for more details.”h]”hX  All of the accesses following the comparison are stores,
so that a control dependency preserves the needed ordering.
That said, it is easy to get control dependencies wrong.
Please see the â€œCONTROL DEPENDENCIESâ€ section of
Documentation/memory-barriers.txt for more details.”…””}”(hj¹  hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h K¿hj³  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hj  ubhø)”}”(hXº  The pointers are not equal *and* the compiler does
not have enough information to deduce the value of the
pointer.  Note that the volatile cast in rcu_dereference()
will normally prevent the compiler from knowing too much.

However, please note that if the compiler knows that the
pointer takes on only one of two values, a not-equal
comparison will provide exactly the information that the
compiler needs to deduce the value of the pointer.
”h]”(hÆ)”}”(hŒÞThe pointers are not equal *and* the compiler does
not have enough information to deduce the value of the
pointer.  Note that the volatile cast in rcu_dereference()
will normally prevent the compiler from knowing too much.”h]”(hŒThe pointers are not equal ”…””}”(hŒThe pointers are not equal ”hjÏ  hžhhŸNh NubjZ  )”}”(hŒ*and*”h]”hŒand”…””}”(hhhjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hjÏ  ubhŒ¾ the compiler does
not have enough information to deduce the value of the
pointer.  Note that the volatile cast in rcu_dereference()
will normally prevent the compiler from knowing too much.”…””}”(hŒ¾ the compiler does
not have enough information to deduce the value of the
pointer.  Note that the volatile cast in rcu_dereference()
will normally prevent the compiler from knowing too much.”hjÏ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KÅhjË  ubhÆ)”}”(hŒÙHowever, please note that if the compiler knows that the
pointer takes on only one of two values, a not-equal
comparison will provide exactly the information that the
compiler needs to deduce the value of the pointer.”h]”hŒÙHowever, please note that if the compiler knows that the
pointer takes on only one of two values, a not-equal
comparison will provide exactly the information that the
compiler needs to deduce the value of the pointer.”…””}”(hjó  hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KÊhjË  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hj  ubeh}”(h]”h ]”h"]”h$]”h&]”j˜  j™  uh1hòhŸh¯h Kƒhj%  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸNh Nubhø)”}”(hX  Disable any value-speculation optimizations that your compiler
might provide, especially if you are making use of feedback-based
optimizations that take data collected from prior runs.  Such
value-speculation optimizations reorder operations by design.

There is one exception to this rule:  Value-speculation
optimizations that leverage the branch-prediction hardware are
safe on strongly ordered systems (such as x86), but not on weakly
ordered systems (such as ARM or Power).  Choose your compiler
command-line options wisely!

”h]”(hÆ)”}”(hŒüDisable any value-speculation optimizations that your compiler
might provide, especially if you are making use of feedback-based
optimizations that take data collected from prior runs.  Such
value-speculation optimizations reorder operations by design.”h]”hŒüDisable any value-speculation optimizations that your compiler
might provide, especially if you are making use of feedback-based
optimizations that take data collected from prior runs.  Such
value-speculation optimizations reorder operations by design.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KÏhj  ubhÆ)”}”(hX  There is one exception to this rule:  Value-speculation
optimizations that leverage the branch-prediction hardware are
safe on strongly ordered systems (such as x86), but not on weakly
ordered systems (such as ARM or Power).  Choose your compiler
command-line options wisely!”h]”hX  There is one exception to this rule:  Value-speculation
optimizations that leverage the branch-prediction hardware are
safe on strongly ordered systems (such as x86), but not on weakly
ordered systems (such as ARM or Power).  Choose your compiler
command-line options wisely!”…””}”(hj%  hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KÔhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hhôhžhhŸh¯h Nubeh}”(h]”h ]”h"]”h$]”h&]”j˜  j™  uh1hòhŸh¯h Khh²hžhubh±)”}”(hhh]”(h¶)”}”(hŒ"EXAMPLE OF AMPLIFIED RCU-USAGE BUG”h]”hŒ"EXAMPLE OF AMPLIFIED RCU-USAGE BUG”…””}”(hjB  hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhj=  hžhhŸh¯h KÜubhÆ)”}”(hX  Because updaters can run concurrently with RCU readers, RCU readers can
see stale and/or inconsistent values.  If RCU readers need fresh or
consistent values, which they sometimes do, they need to take proper
precautions.  To see this, consider the following code fragment::”h]”hX  Because updaters can run concurrently with RCU readers, RCU readers can
see stale and/or inconsistent values.  If RCU readers need fresh or
consistent values, which they sometimes do, they need to take proper
precautions.  To see this, consider the following code fragment:”…””}”(hX  Because updaters can run concurrently with RCU readers, RCU readers can
see stale and/or inconsistent values.  If RCU readers need fresh or
consistent values, which they sometimes do, they need to take proper
precautions.  To see this, consider the following code fragment:”hjN  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h KÞhj=  hžhubj   )”}”(hX#  struct foo {
        int a;
        int b;
        int c;
};
struct foo *gp1;
struct foo *gp2;

void updater(void)
{
        struct foo *p;

        p = kmalloc(...);
        if (p == NULL)
                deal_with_it();
        p->a = 42;  /* Each field in its own cache line. */
        p->b = 43;
        p->c = 44;
        rcu_assign_pointer(gp1, p);
        p->b = 143;
        p->c = 144;
        rcu_assign_pointer(gp2, p);
}

void reader(void)
{
        struct foo *p;
        struct foo *q;
        int r1, r2;

        rcu_read_lock();
        p = rcu_dereference(gp2);
        if (p == NULL)
                return;
        r1 = p->b;  /* Guaranteed to get 143. */
        q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
        if (p == q) {
                /* The compiler decides that q->c is same as p->c. */
                r2 = p->c; /* Could get 44 on weakly order system. */
        } else {
                r2 = p->c - r1; /* Unconditional access to p->c. */
        }
        rcu_read_unlock();
        do_something_with(r1, r2);
}”h]”hX#  struct foo {
        int a;
        int b;
        int c;
};
struct foo *gp1;
struct foo *gp2;

void updater(void)
{
        struct foo *p;

        p = kmalloc(...);
        if (p == NULL)
                deal_with_it();
        p->a = 42;  /* Each field in its own cache line. */
        p->b = 43;
        p->c = 44;
        rcu_assign_pointer(gp1, p);
        p->b = 143;
        p->c = 144;
        rcu_assign_pointer(gp2, p);
}

void reader(void)
{
        struct foo *p;
        struct foo *q;
        int r1, r2;

        rcu_read_lock();
        p = rcu_dereference(gp2);
        if (p == NULL)
                return;
        r1 = p->b;  /* Guaranteed to get 143. */
        q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
        if (p == q) {
                /* The compiler decides that q->c is same as p->c. */
                r2 = p->c; /* Could get 44 on weakly order system. */
        } else {
                r2 = p->c - r1; /* Unconditional access to p->c. */
        }
        rcu_read_unlock();
        do_something_with(r1, r2);
}”…””}”(hhhj]  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Kãhj=  hžhubhÆ)”}”(hXd  You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
but you should not be.  After all, the updater might have been invoked
a second time between the time reader() loaded into "r1" and the time
that it loaded into "r2".  The fact that this same result can occur due
to some reordering from the compiler and CPUs is beside the point.”h]”hXl  You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
but you should not be.  After all, the updater might have been invoked
a second time between the time reader() loaded into â€œr1â€ and the time
that it loaded into â€œr2â€.  The fact that this same result can occur due
to some reordering from the compiler and CPUs is beside the point.”…””}”(hjm  hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mhj=  hžhubhÆ)”}”(hŒ4But suppose that the reader needs a consistent view?”h]”hŒ4But suppose that the reader needs a consistent view?”…””}”(hj{  hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mhj=  hžhubhÆ)”}”(hŒ>Then one approach is to use locking, for example, as follows::”h]”hŒ=Then one approach is to use locking, for example, as follows:”…””}”(hŒ=Then one approach is to use locking, for example, as follows:”hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mhj=  hžhubj   )”}”(hX  struct foo {
        int a;
        int b;
        int c;
        spinlock_t lock;
};
struct foo *gp1;
struct foo *gp2;

void updater(void)
{
        struct foo *p;

        p = kmalloc(...);
        if (p == NULL)
                deal_with_it();
        spin_lock(&p->lock);
        p->a = 42;  /* Each field in its own cache line. */
        p->b = 43;
        p->c = 44;
        spin_unlock(&p->lock);
        rcu_assign_pointer(gp1, p);
        spin_lock(&p->lock);
        p->b = 143;
        p->c = 144;
        spin_unlock(&p->lock);
        rcu_assign_pointer(gp2, p);
}

void reader(void)
{
        struct foo *p;
        struct foo *q;
        int r1, r2;

        rcu_read_lock();
        p = rcu_dereference(gp2);
        if (p == NULL)
                return;
        spin_lock(&p->lock);
        r1 = p->b;  /* Guaranteed to get 143. */
        q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
        if (p == q) {
                /* The compiler decides that q->c is same as p->c. */
                r2 = p->c; /* Locking guarantees r2 == 144. */
        } else {
                spin_lock(&q->lock);
                r2 = q->c - r1;
                spin_unlock(&q->lock);
        }
        rcu_read_unlock();
        spin_unlock(&p->lock);
        do_something_with(r1, r2);
}”h]”hX  struct foo {
        int a;
        int b;
        int c;
        spinlock_t lock;
};
struct foo *gp1;
struct foo *gp2;

void updater(void)
{
        struct foo *p;

        p = kmalloc(...);
        if (p == NULL)
                deal_with_it();
        spin_lock(&p->lock);
        p->a = 42;  /* Each field in its own cache line. */
        p->b = 43;
        p->c = 44;
        spin_unlock(&p->lock);
        rcu_assign_pointer(gp1, p);
        spin_lock(&p->lock);
        p->b = 143;
        p->c = 144;
        spin_unlock(&p->lock);
        rcu_assign_pointer(gp2, p);
}

void reader(void)
{
        struct foo *p;
        struct foo *q;
        int r1, r2;

        rcu_read_lock();
        p = rcu_dereference(gp2);
        if (p == NULL)
                return;
        spin_lock(&p->lock);
        r1 = p->b;  /* Guaranteed to get 143. */
        q = rcu_dereference(gp1);  /* Guaranteed non-NULL. */
        if (p == q) {
                /* The compiler decides that q->c is same as p->c. */
                r2 = p->c; /* Locking guarantees r2 == 144. */
        } else {
                spin_lock(&q->lock);
                r2 = q->c - r1;
                spin_unlock(&q->lock);
        }
        rcu_read_unlock();
        spin_unlock(&p->lock);
        do_something_with(r1, r2);
}”…””}”(hhhj–  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Mhj=  hžhubhÆ)”}”(hŒ*As always, use the right tool for the job!”h]”hŒ*As always, use the right tool for the job!”…””}”(hj¦  hj¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h MRhj=  hžhubeh}”(h]”Œ"example-of-amplified-rcu-usage-bug”ah ]”h"]”Œ"example of amplified rcu-usage bug”ah$]”h&]”uh1h°hh²hžhhŸh¯h KÜubh±)”}”(hhh]”(h¶)”}”(hŒ)EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH”h]”hŒ)EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH”…””}”(hj¿  hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhjº  hžhhŸh¯h MVubhÆ)”}”(hXŸ  If a pointer obtained from rcu_dereference() compares not-equal to some
other pointer, the compiler normally has no clue what the value of the
first pointer might be.  This lack of knowledge prevents the compiler
from carrying out optimizations that otherwise might destroy the ordering
guarantees that RCU depends on.  And the volatile cast in rcu_dereference()
should prevent the compiler from guessing the value.”h]”hXŸ  If a pointer obtained from rcu_dereference() compares not-equal to some
other pointer, the compiler normally has no clue what the value of the
first pointer might be.  This lack of knowledge prevents the compiler
from carrying out optimizations that otherwise might destroy the ordering
guarantees that RCU depends on.  And the volatile cast in rcu_dereference()
should prevent the compiler from guessing the value.”…””}”(hjÍ  hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h MXhjº  hžhubhÆ)”}”(hŒuBut without rcu_dereference(), the compiler knows more than you might
expect.  Consider the following code fragment::”h]”hŒtBut without rcu_dereference(), the compiler knows more than you might
expect.  Consider the following code fragment:”…””}”(hŒtBut without rcu_dereference(), the compiler knows more than you might
expect.  Consider the following code fragment:”hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M_hjº  hžhubj   )”}”(hXy  struct foo {
        int a;
        int b;
};
static struct foo variable1;
static struct foo variable2;
static struct foo *gp = &variable1;

void updater(void)
{
        initialize_foo(&variable2);
        rcu_assign_pointer(gp, &variable2);
        /*
         * The above is the only store to gp in this translation unit,
         * and the address of gp is not exported in any way.
         */
}

int reader(void)
{
        struct foo *p;

        p = gp;
        barrier();
        if (p == &variable1)
                return p->a; /* Must be variable1.a. */
        else
                return p->b; /* Must be variable2.b. */
}”h]”hXy  struct foo {
        int a;
        int b;
};
static struct foo variable1;
static struct foo variable2;
static struct foo *gp = &variable1;

void updater(void)
{
        initialize_foo(&variable2);
        rcu_assign_pointer(gp, &variable2);
        /*
         * The above is the only store to gp in this translation unit,
         * and the address of gp is not exported in any way.
         */
}

int reader(void)
{
        struct foo *p;

        p = gp;
        barrier();
        if (p == &variable1)
                return p->a; /* Must be variable1.a. */
        else
                return p->b; /* Must be variable2.b. */
}”…””}”(hhhjè  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Mbhjº  hžhubhÆ)”}”(hX  Because the compiler can see all stores to "gp", it knows that the only
possible values of "gp" are "variable1" on the one hand and "variable2"
on the other.  The comparison in reader() therefore tells the compiler
the exact value of "p" even in the not-equals case.  This allows the
compiler to make the return values independent of the load from "gp",
in turn destroying the ordering between this load and the loads of the
return values.  This can result in "p->b" returning pre-initialization
garbage values on weakly ordered systems.”h]”hX5  Because the compiler can see all stores to â€œgpâ€, it knows that the only
possible values of â€œgpâ€ are â€œvariable1â€ on the one hand and â€œvariable2â€
on the other.  The comparison in reader() therefore tells the compiler
the exact value of â€œpâ€ even in the not-equals case.  This allows the
compiler to make the return values independent of the load from â€œgpâ€,
in turn destroying the ordering between this load and the loads of the
return values.  This can result in â€œp->bâ€ returning pre-initialization
garbage values on weakly ordered systems.”…””}”(hjø  hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M€hjº  hžhubhÆ)”}”(hŒfIn short, rcu_dereference() is *not* optional when you are going to
dereference the resulting pointer.”h]”(hŒIn short, rcu_dereference() is ”…””}”(hŒIn short, rcu_dereference() is ”hj  hžhhŸNh NubjZ  )”}”(hŒ*not*”h]”hŒnot”…””}”(hhhj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hj  ubhŒB optional when you are going to
dereference the resulting pointer.”…””}”(hŒB optional when you are going to
dereference the resulting pointer.”hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M‰hjº  hžhubeh}”(h]”Œ)example-where-the-compiler-knows-too-much”ah ]”h"]”Œ)example where the compiler knows too much”ah$]”h&]”uh1h°hh²hžhhŸh¯h MVubh±)”}”(hhh]”(h¶)”}”(hŒ<WHICH MEMBER OF THE rcu_dereference() FAMILY SHOULD YOU USE?”h]”hŒ<WHICH MEMBER OF THE rcu_dereference() FAMILY SHOULD YOU USE?”…””}”(hj3  hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhj.  hžhhŸh¯h MŽubhÆ)”}”(hXQ  First, please avoid using rcu_dereference_raw() and also please avoid
using rcu_dereference_check() and rcu_dereference_protected() with a
second argument with a constant value of 1 (or true, for that matter).
With that caution out of the way, here is some guidance for which
member of the rcu_dereference() to use in various situations:”h]”hXQ  First, please avoid using rcu_dereference_raw() and also please avoid
using rcu_dereference_check() and rcu_dereference_protected() with a
second argument with a constant value of 1 (or true, for that matter).
With that caution out of the way, here is some guidance for which
member of the rcu_dereference() to use in various situations:”…””}”(hjA  hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mhj.  hžhubhŒenumerated_list”“”)”}”(hhh]”(hø)”}”(hXì  If the access needs to be within an RCU read-side critical
section, use rcu_dereference().  With the new consolidated
RCU flavors, an RCU read-side critical section is entered
using rcu_read_lock(), anything that disables bottom halves,
anything that disables interrupts, or anything that disables
preemption.  Please note that spinlock critical sections
are also implied RCU read-side critical sections, even when
they are preemptible, as they are in kernels built with
CONFIG_PREEMPT_RT=y.
”h]”hÆ)”}”(hXë  If the access needs to be within an RCU read-side critical
section, use rcu_dereference().  With the new consolidated
RCU flavors, an RCU read-side critical section is entered
using rcu_read_lock(), anything that disables bottom halves,
anything that disables interrupts, or anything that disables
preemption.  Please note that spinlock critical sections
are also implied RCU read-side critical sections, even when
they are preemptible, as they are in kernels built with
CONFIG_PREEMPT_RT=y.”h]”hXë  If the access needs to be within an RCU read-side critical
section, use rcu_dereference().  With the new consolidated
RCU flavors, an RCU read-side critical section is entered
using rcu_read_lock(), anything that disables bottom halves,
anything that disables interrupts, or anything that disables
preemption.  Please note that spinlock critical sections
are also implied RCU read-side critical sections, even when
they are preemptible, as they are in kernels built with
CONFIG_PREEMPT_RT=y.”…””}”(hjX  hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M–hjR  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjO  hžhhŸh¯h Nubhø)”}”(hX&  If the access might be within an RCU read-side critical section
on the one hand, or protected by (say) my_lock on the other,
use rcu_dereference_check(), for example::

        p1 = rcu_dereference_check(p->rcu_protected_pointer,
                                   lockdep_is_held(&my_lock));

”h]”(hÆ)”}”(hŒ§If the access might be within an RCU read-side critical section
on the one hand, or protected by (say) my_lock on the other,
use rcu_dereference_check(), for example::”h]”hŒ¦If the access might be within an RCU read-side critical section
on the one hand, or protected by (say) my_lock on the other,
use rcu_dereference_check(), for example:”…””}”(hŒ¦If the access might be within an RCU read-side critical section
on the one hand, or protected by (say) my_lock on the other,
use rcu_dereference_check(), for example:”hjn  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M hjj  ubj   )”}”(hŒkp1 = rcu_dereference_check(p->rcu_protected_pointer,
                           lockdep_is_held(&my_lock));”h]”hŒkp1 = rcu_dereference_check(p->rcu_protected_pointer,
                           lockdep_is_held(&my_lock));”…””}”(hhhj}  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h M¤hjj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjO  hžhhŸh¯h Nubhø)”}”(hX{  If the access might be within an RCU read-side critical section
on the one hand, or protected by either my_lock or your_lock on
the other, again use rcu_dereference_check(), for example::

        p1 = rcu_dereference_check(p->rcu_protected_pointer,
                                   lockdep_is_held(&my_lock) ||
                                   lockdep_is_held(&your_lock));
”h]”(hÆ)”}”(hŒ»If the access might be within an RCU read-side critical section
on the one hand, or protected by either my_lock or your_lock on
the other, again use rcu_dereference_check(), for example::”h]”hŒºIf the access might be within an RCU read-side critical section
on the one hand, or protected by either my_lock or your_lock on
the other, again use rcu_dereference_check(), for example:”…””}”(hŒºIf the access might be within an RCU read-side critical section
on the one hand, or protected by either my_lock or your_lock on
the other, again use rcu_dereference_check(), for example:”hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M¨hj‘  ubj   )”}”(hŒ¥p1 = rcu_dereference_check(p->rcu_protected_pointer,
                           lockdep_is_held(&my_lock) ||
                           lockdep_is_held(&your_lock));”h]”hŒ¥p1 = rcu_dereference_check(p->rcu_protected_pointer,
                           lockdep_is_held(&my_lock) ||
                           lockdep_is_held(&your_lock));”…””}”(hhhj¤  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h M¬hj‘  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjO  hžhhŸh¯h Nubhø)”}”(hXr  If the access is on the update side, so that it is always protected
by my_lock, use rcu_dereference_protected()::

        p1 = rcu_dereference_protected(p->rcu_protected_pointer,
                                       lockdep_is_held(&my_lock));

This can be extended to handle multiple locks as in #3 above,
and both can be extended to check other conditions as well.
”h]”(hÆ)”}”(hŒqIf the access is on the update side, so that it is always protected
by my_lock, use rcu_dereference_protected()::”h]”hŒpIf the access is on the update side, so that it is always protected
by my_lock, use rcu_dereference_protected():”…””}”(hŒpIf the access is on the update side, so that it is always protected
by my_lock, use rcu_dereference_protected():”hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M°hj¸  ubj   )”}”(hŒsp1 = rcu_dereference_protected(p->rcu_protected_pointer,
                               lockdep_is_held(&my_lock));”h]”hŒsp1 = rcu_dereference_protected(p->rcu_protected_pointer,
                               lockdep_is_held(&my_lock));”…””}”(hhhjË  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h M³hj¸  ubhÆ)”}”(hŒyThis can be extended to handle multiple locks as in #3 above,
and both can be extended to check other conditions as well.”h]”hŒyThis can be extended to handle multiple locks as in #3 above,
and both can be extended to check other conditions as well.”…””}”(hjÛ  hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M¶hj¸  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjO  hžhhŸh¯h Nubhø)”}”(hX  If the protection is supplied by the caller, and is thus unknown
to this code, that is the rare case when rcu_dereference_raw()
is appropriate.  In addition, rcu_dereference_raw() might be
appropriate when the lockdep expression would be excessively
complex, except that a better approach in that case might be to
take a long hard look at your synchronization design.  Still,
there are data-locking cases where any one of a very large number
of locks or reference counters suffices to protect the pointer,
so rcu_dereference_raw() does have its place.

However, its place is probably quite a bit smaller than one
might expect given the number of uses in the current kernel.
Ditto for its synonym, rcu_dereference_check( ... , 1), and
its close relative, rcu_dereference_protected(... , 1).

”h]”(hÆ)”}”(hX'  If the protection is supplied by the caller, and is thus unknown
to this code, that is the rare case when rcu_dereference_raw()
is appropriate.  In addition, rcu_dereference_raw() might be
appropriate when the lockdep expression would be excessively
complex, except that a better approach in that case might be to
take a long hard look at your synchronization design.  Still,
there are data-locking cases where any one of a very large number
of locks or reference counters suffices to protect the pointer,
so rcu_dereference_raw() does have its place.”h]”hX'  If the protection is supplied by the caller, and is thus unknown
to this code, that is the rare case when rcu_dereference_raw()
is appropriate.  In addition, rcu_dereference_raw() might be
appropriate when the lockdep expression would be excessively
complex, except that a better approach in that case might be to
take a long hard look at your synchronization design.  Still,
there are data-locking cases where any one of a very large number
of locks or reference counters suffices to protect the pointer,
so rcu_dereference_raw() does have its place.”…””}”(hjó  hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h M¹hjí  ubhÆ)”}”(hŒìHowever, its place is probably quite a bit smaller than one
might expect given the number of uses in the current kernel.
Ditto for its synonym, rcu_dereference_check( ... , 1), and
its close relative, rcu_dereference_protected(... , 1).”h]”hŒìHowever, its place is probably quite a bit smaller than one
might expect given the number of uses in the current kernel.
Ditto for its synonym, rcu_dereference_check( ... , 1), and
its close relative, rcu_dereference_protected(... , 1).”…””}”(hj  hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h MÃhjí  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1h÷hjO  hžhhŸh¯h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jM  hj.  hžhhŸh¯h M–ubeh}”(h]”Œ9which-member-of-the-rcu-dereference-family-should-you-use”ah ]”h"]”Œ<which member of the rcu_dereference() family should you use?”ah$]”h&]”uh1h°hh²hžhhŸh¯h MŽubh±)”}”(hhh]”(h¶)”}”(hŒ)SPARSE CHECKING OF RCU-PROTECTED POINTERS”h]”hŒ)SPARSE CHECKING OF RCU-PROTECTED POINTERS”…””}”(hj+  hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hµhj&  hžhhŸh¯h MÊubhÆ)”}”(hX  The sparse static-analysis tool checks for non-RCU access to RCU-protected
pointers, which can result in "interesting" bugs due to compiler
optimizations involving invented loads and perhaps also load tearing.
For example, suppose someone mistakenly does something like this::”h]”hX  The sparse static-analysis tool checks for non-RCU access to RCU-protected
pointers, which can result in â€œinterestingâ€ bugs due to compiler
optimizations involving invented loads and perhaps also load tearing.
For example, suppose someone mistakenly does something like this:”…””}”(hX  The sparse static-analysis tool checks for non-RCU access to RCU-protected
pointers, which can result in "interesting" bugs due to compiler
optimizations involving invented loads and perhaps also load tearing.
For example, suppose someone mistakenly does something like this:”hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h MÌhj&  hžhubj   )”}”(hŒTp = q->rcu_protected_pointer;
do_something_with(p->a);
do_something_else_with(p->b);”h]”hŒTp = q->rcu_protected_pointer;
do_something_with(p->a);
do_something_else_with(p->b);”…””}”(hhhjF  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h MÑhj&  hžhubhÆ)”}”(hŒ~If register pressure is high, the compiler might optimize "p" out
of existence, transforming the code to something like this::”h]”hŒIf register pressure is high, the compiler might optimize â€œpâ€ out
of existence, transforming the code to something like this:”…””}”(hŒ}If register pressure is high, the compiler might optimize "p" out
of existence, transforming the code to something like this:”hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h MÕhj&  hžhubj   )”}”(hŒddo_something_with(q->rcu_protected_pointer->a);
do_something_else_with(q->rcu_protected_pointer->b);”h]”hŒddo_something_with(q->rcu_protected_pointer->a);
do_something_else_with(q->rcu_protected_pointer->b);”…””}”(hhhjc  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h MØhj&  hžhubhÆ)”}”(hX  This could fatally disappoint your code if q->rcu_protected_pointer
changed in the meantime.  Nor is this a theoretical problem:  Exactly
this sort of bug cost Paul E. McKenney (and several of his innocent
colleagues) a three-day weekend back in the early 1990s.”h]”hX  This could fatally disappoint your code if q->rcu_protected_pointer
changed in the meantime.  Nor is this a theoretical problem:  Exactly
this sort of bug cost Paul E. McKenney (and several of his innocent
colleagues) a three-day weekend back in the early 1990s.”…””}”(hjs  hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h MÛhj&  hžhubhÆ)”}”(hŒƒLoad tearing could of course result in dereferencing a mashup of a pair
of pointers, which also might fatally disappoint your code.”h]”hŒƒLoad tearing could of course result in dereferencing a mashup of a pair
of pointers, which also might fatally disappoint your code.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Màhj&  hžhubhÆ)”}”(hŒZThese problems could have been avoided simply by making the code instead
read as follows::”h]”hŒYThese problems could have been avoided simply by making the code instead
read as follows:”…””•S      }”(hŒYThese problems could have been avoided simply by making the code instead
read as follows:”hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mãhj&  hžhubj   )”}”(hŒep = rcu_dereference(q->rcu_protected_pointer);
do_something_with(p->a);
do_something_else_with(p->b);”h]”hŒep = rcu_dereference(q->rcu_protected_pointer);
do_something_with(p->a);
do_something_else_with(p->b);”…””}”(hhhjœ  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Mæhj&  hžhubhÆ)”}”(hX  Unfortunately, these sorts of bugs can be extremely hard to spot during
review.  This is where the sparse tool comes into play, along with the
"__rcu" marker.  If you mark a pointer declaration, whether in a structure
or as a formal parameter, with "__rcu", which tells sparse to complain if
this pointer is accessed directly.  It will also cause sparse to complain
if a pointer not marked with "__rcu" is accessed using rcu_dereference()
and friends.  For example, ->rcu_protected_pointer might be declared as
follows::”h]”hX  Unfortunately, these sorts of bugs can be extremely hard to spot during
review.  This is where the sparse tool comes into play, along with the
â€œ__rcuâ€ marker.  If you mark a pointer declaration, whether in a structure
or as a formal parameter, with â€œ__rcuâ€, which tells sparse to complain if
this pointer is accessed directly.  It will also cause sparse to complain
if a pointer not marked with â€œ__rcuâ€ is accessed using rcu_dereference()
and friends.  For example, ->rcu_protected_pointer might be declared as
follows:”…””}”(hX  Unfortunately, these sorts of bugs can be extremely hard to spot during
review.  This is where the sparse tool comes into play, along with the
"__rcu" marker.  If you mark a pointer declaration, whether in a structure
or as a formal parameter, with "__rcu", which tells sparse to complain if
this pointer is accessed directly.  It will also cause sparse to complain
if a pointer not marked with "__rcu" is accessed using rcu_dereference()
and friends.  For example, ->rcu_protected_pointer might be declared as
follows:”hjª  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mêhj&  hžhubj   )”}”(hŒ(struct foo __rcu *rcu_protected_pointer;”h]”hŒ(struct foo __rcu *rcu_protected_pointer;”…””}”(hhhj¹  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jÿ  hŸh¯h Móhj&  hžhubhÆ)”}”(hŒcUse of "__rcu" is opt-in.  If you choose not to use it, then you should
ignore the sparse warnings.”h]”hŒgUse of â€œ__rcuâ€ is opt-in.  If you choose not to use it, then you should
ignore the sparse warnings.”…””}”(hjÉ  hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhŸh¯h Mõhj&  hžhubeh}”(h]”Œ)sparse-checking-of-rcu-protected-pointers”ah ]”h"]”Œ)sparse checking of rcu-protected pointers”ah$]”h&]”uh1h°hh²hžhhŸh¯h MÊubeh}”(h]”(Œ=proper-care-and-feeding-of-return-values-from-rcu-dereference”h®eh ]”h"]”(Œ?proper care and feeding of return values from rcu_dereference()”Œrcu_dereference_doc”eh$]”h&]”uh1h°hhhžhhŸh¯h KŒexpect_referenced_by_name”}”jã  h£sŒexpect_referenced_by_id”}”h®h£subeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¯uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hµNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”ŒUTF-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¯Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œembed_images”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”h®]”h£asŒnameids”}”(jã  h®jâ  jß  j·  j´  j+  j(  j#  j   jÚ  j×  uŒ	nametypes”}”(jã  ˆjâ  Nj·  Nj+  Nj#  NjÚ  Nuh}”(h®h²jß  h²j´  j=  j(  jº  j   j.  j×  j&  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hÆ)”}”(hhh]”hŒ9Hyperlink target "rcu-dereference-doc" is not referenced.”…””}”(hhhjx  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÅhju  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h¯Œline”Kuh1js  ubaŒtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.