aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Documentation/memory-barriers.txt52
1 files changed, 33 insertions, 19 deletions
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index f8550310a6d5..528d52f52eeb 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -829,8 +829,8 @@ There are some more advanced barrier functions:
829 (*) smp_mb__after_atomic_inc(); 829 (*) smp_mb__after_atomic_inc();
830 830
831 These are for use with atomic add, subtract, increment and decrement 831 These are for use with atomic add, subtract, increment and decrement
832 functions, especially when used for reference counting. These functions 832 functions that don't return a value, especially when used for reference
833 do not imply memory barriers. 833 counting. These functions do not imply memory barriers.
834 834
835 As an example, consider a piece of code that marks an object as being dead 835 As an example, consider a piece of code that marks an object as being dead
836 and then decrements the object's reference count: 836 and then decrements the object's reference count:
@@ -1263,15 +1263,17 @@ else.
1263ATOMIC OPERATIONS 1263ATOMIC OPERATIONS
1264----------------- 1264-----------------
1265 1265
1266Though they are technically interprocessor interaction considerations, atomic 1266Whilst they are technically interprocessor interaction considerations, atomic
1267operations are noted specially as they do _not_ generally imply memory 1267operations are noted specially as some of them imply full memory barriers and
1268barriers. The possible offenders include: 1268some don't, but they're very heavily relied on as a group throughout the
1269kernel.
1270
1271Any atomic operation that modifies some state in memory and returns information
1272about the state (old or new) implies an SMP-conditional general memory barrier
1273(smp_mb()) on each side of the actual operation. These include:
1269 1274
1270 xchg(); 1275 xchg();
1271 cmpxchg(); 1276 cmpxchg();
1272 test_and_set_bit();
1273 test_and_clear_bit();
1274 test_and_change_bit();
1275 atomic_cmpxchg(); 1277 atomic_cmpxchg();
1276 atomic_inc_return(); 1278 atomic_inc_return();
1277 atomic_dec_return(); 1279 atomic_dec_return();
@@ -1282,21 +1284,31 @@ barriers. The possible offenders include:
1282 atomic_sub_and_test(); 1284 atomic_sub_and_test();
1283 atomic_add_negative(); 1285 atomic_add_negative();
1284 atomic_add_unless(); 1286 atomic_add_unless();
1287 test_and_set_bit();
1288 test_and_clear_bit();
1289 test_and_change_bit();
1290
1291These are used for such things as implementing LOCK-class and UNLOCK-class
1292operations and adjusting reference counters towards object destruction, and as
1293such the implicit memory barrier effects are necessary.
1285 1294
1286These may be used for such things as implementing LOCK operations or controlling
1287the lifetime of objects by decreasing their reference counts. In such cases
1288they need preceding memory barriers.
1289 1295
1290The following may also be possible offenders as they may be used as UNLOCK 1296The following operation are potential problems as they do _not_ imply memory
1291operations. 1297barriers, but might be used for implementing such things as UNLOCK-class
1298operations:
1292 1299
1300 atomic_set();
1293 set_bit(); 1301 set_bit();
1294 clear_bit(); 1302 clear_bit();
1295 change_bit(); 1303 change_bit();
1296 atomic_set(); 1304
1305With these the appropriate explicit memory barrier should be used if necessary
1306(smp_mb__before_clear_bit() for instance).
1297 1307
1298 1308
1299The following are a little tricky: 1309The following also do _not_ imply memory barriers, and so may require explicit
1310memory barriers under some circumstances (smp_mb__before_atomic_dec() for
1311instance)):
1300 1312
1301 atomic_add(); 1313 atomic_add();
1302 atomic_sub(); 1314 atomic_sub();
@@ -1317,10 +1329,12 @@ specific order.
1317 1329
1318 1330
1319Basically, each usage case has to be carefully considered as to whether memory 1331Basically, each usage case has to be carefully considered as to whether memory
1320barriers are needed or not. The simplest rule is probably: if the atomic 1332barriers are needed or not.
1321operation is protected by a lock, then it does not require a barrier unless 1333
1322there's another operation within the critical section with respect to which an 1334[!] Note that special memory barrier primitives are available for these
1323ordering must be maintained. 1335situations because on some CPUs the atomic instructions used imply full memory
1336barriers, and so barrier instructions are superfluous in conjunction with them,
1337and in such cases the special barrier primitives will be no-ops.
1324 1338
1325See Documentation/atomic_ops.txt for more information. 1339See Documentation/atomic_ops.txt for more information.
1326 1340