lkml.org 
[lkml]   [2021]   [Dec]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
From
Subject[RFC][PATCH 5/5] atomic: Document the atomic_{}_ofl() functions
Them special, them cause confusion, them needing docs for reading.

Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
---
Documentation/atomic_t.txt | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)

--- a/Documentation/atomic_t.txt
+++ b/Documentation/atomic_t.txt
@@ -44,6 +44,10 @@ The 'full' API consists of (atomic64_ an
atomic_add_unless(), atomic_inc_not_zero()
atomic_sub_and_test(), atomic_dec_and_test()

+Reference count with overflow (as used by refcount_t):
+
+ atomic_inc_ofl(), atomic_dec_ofl()
+ atomic_dec_and_test_ofl()

Misc:

@@ -157,6 +161,22 @@ atomic variable) can be fully ordered an
visible.


+Overflow ops:
+
+The atomic_{}_ofl() ops are similar to their !_ofl() bretheren with the
+notable exception that they take a label as their final argument to jump to
+when the atomic op overflows.
+
+Overflow for inc is zero-or-negative on the value prior to increment.
+Overflow for dec is zero-or-negative on the value after the decrement.
+Overflow for dec_and_test is negative on the value after the decrement.
+
+These semantics match the reference count use-case (for which they were
+created). Specifically incrementing from zero is a failure because 0 means the
+object is freed (IOW use-after-free). decrementing to zero is a failure
+because it goes undetected (see dec_and_test) and the object would leak.
+
+
ORDERING (go read memory-barriers.txt first)
--------


\
 
 \ /
  Last update: 2021-12-08 19:41    [W:0.342 / U:0.052 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site