linux-kernel - [RFC][PATCH 5/5] atomic: Document the atomic_{}

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20211208183906.703599388@infradead.org>
Date:   Wed, 08 Dec 2021 19:37:00 +0100
From:   Peter Zijlstra <peterz@...radead.org>
To:     will@...nel.org, boqun.feng@...il.com
Cc:     linux-kernel@...r.kernel.org, x86@...nel.org, peterz@...radead.org,
        mark.rutland@....com, elver@...gle.com, keescook@...omium.org,
        hch@...radead.org, torvalds@...ux-foundation.org
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@...radead.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)
 --------