diff options
author | Paul E. McKenney <paulmck@kernel.org> | 2023-10-20 20:51:26 +0300 |
---|---|---|
committer | Neeraj Upadhyay (AMD) <neeraj.iitr10@gmail.com> | 2023-12-13 22:46:28 +0300 |
commit | c49956be75152a533787f5daa06ef4b710207499 (patch) | |
tree | 42d45baf3b74c8747bef2e48154ebc72df586660 /Documentation/RCU/rcu_dereference.rst | |
parent | 1b7178b23dc915fc6801ff3eeb6c4ffa51b562f7 (diff) | |
download | linux-c49956be75152a533787f5daa06ef4b710207499.tar.xz |
doc: Mention address and data dependencies in rcu_dereference.rst
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>
Diffstat (limited to 'Documentation/RCU/rcu_dereference.rst')
-rw-r--r-- | Documentation/RCU/rcu_dereference.rst | 27 |
1 files changed, 20 insertions, 7 deletions
diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index 3b739f6243c8..659d5913784d 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -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. - -It is nevertheless possible to get into trouble with other operations. -Follow these rules to keep your RCU code working properly: +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). + +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 |