Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-21 19:41:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Mention address and data dependencies in rcu_dereference.rst

Browse Source 
This commit adds discussion of address and data dependencies to the
beginning of rcu_dereference.rst in order to enable readers to more
easily make the connection to the Linux-kernel memory model in general
and to memory-barriers.txt in particular.

Reported-by: Jonas Oberhauser <jonas.oberhauser@huaweicloud.com>
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com>
This commit is contained in:
Paul E. McKenney 2023-10-20 10:51:26 -07:00 committed by Neeraj Upadhyay (AMD)
parent 1b7178b23d
commit c49956be75
1 changed files with 19 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Documentation/RCU/rcu_dereference.rst
View File

@ -3,13 +3,26 @@
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.
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).
It is nevertheless possible to get into trouble with other operations.
Follow these rules to keep your RCU code working properly:
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.
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:
- You must use one of the rcu_dereference() family of primitives
to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU