[PATCH 3/5] file_ref: document why file_ref_put() stays fully ordered

[Christian Brauner <brauner@kernel.org>]

The comment above file_ref_put() describes release ordering on the way
in and acquire ordering on success. file_ref_put() uses the fully
ordered atomic_long_dec_return() instead. Document why we need it.

Files are SLAB_TYPESAFE_BY_RCU. When the last reference goes
synchronously, in __fput_sync() and on the fallback path of
fput_close_sync(), the file is freed right after the decrement and
another CPU can get it from the slab and reinitialize the counter at
once. The lookup that increments that recycled counter relies on seeing
the stores the closer made before its put. A release orders those stores
before the decrement, not before the slab handoff that follows it. The
full barrier does. The deferred fput() path has the cmpxchg() in
task_work_add() between the decrement and the free, the synchronous
paths have nothing else.

No functional changes.

Signed-off-by: Christian Brauner (Amutable) <brauner@kernel.org>
---
 include/linux/file_ref.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/include/linux/file_ref.h b/include/linux/file_ref.h
index 4cffb24257e2..e5fc45714fe2 100644
--- a/include/linux/file_ref.h
+++ b/include/linux/file_ref.h
@@ -133,6 +133,17 @@ static __always_inline void file_ref_inc(file_ref_t *ref)
  * are done before, and provides an acquire ordering on success such
  * that free() must come after.
  *
+ * The decrement is fully ordered though and it has to stay that way.
+ * When the last reference goes synchronously, in __fput_sync() and on
+ * the fallback path of fput_close_sync(), the full barrier is what
+ * orders the caller's earlier stores, in close(2) the cleared slot in
+ * the descriptor table, before the slab handoff that lets another CPU
+ * reallocate the file. A lookup that increments the recycled counter
+ * then sees the cleared slot and fails its recheck. The deferred
+ * fput() has the cmpxchg() of task_work_add() for that, the
+ * synchronous paths have nothing else. So this is not a candidate for
+ * atomic_long_dec_return_release().
+ *
  * Return: True if this was the last reference with no future references
  *         possible. This signals the caller that it can safely release
  *         the object which is protected by the reference counter.

-- 
2.53.0