[PATCH 5/5] Documentation: update the lock-free file lookup in files.rst

[Christian Brauner <brauner@kernel.org>]

The lock-free lookup section of files.rst still sends readers to the
lookup_fdget_rcu() helpers that commit 8fd3395ec905 ("get rid of
...lookup...fdget_rcu() family") removed. And the SLAB_TYPESAFE_BY_RCU
paragraph still describes the reference as atomic_long_inc_not_zero()
and points to __files_get_rcu(), which doesn't exist, the lookup is
__fget_files_rcu(). Files have been using file_ref since commit
90ee6ed776c0 ("fs: port files to file_ref").

So point readers to fget() and friends and spell out what the lookup
does now: take the reference with file_ref_get(), reload the pointer,
compare against a copy the compiler can't see through and return the
reloaded pointer. Then say which orderings that rests on, the acquire
in file_ref_get(), the dependency on the reload and the full ordering
of file_ref_put(), and where they are documented and checked:
include/linux/file_ref.h and Documentation/litmus-tests/fs/.

Signed-off-by: Christian Brauner (Amutable) <brauner@kernel.org>
---
 Documentation/filesystems/files.rst | 48 +++++++++++++++++++++++--------------
 1 file changed, 30 insertions(+), 18 deletions(-)

diff --git a/Documentation/filesystems/files.rst b/Documentation/filesystems/files.rst
index eb770f891b27..59536e62ed74 100644
--- a/Documentation/filesystems/files.rst
+++ b/Documentation/filesystems/files.rst
@@ -61,29 +61,32 @@ the fdtable structure -
 3. For any update to the fd table, files->file_lock must
    be held.
 
-4. To look up the file structure given an fd, a reader
-   must use either lookup_fdget_rcu() or files_lookup_fdget_rcu() APIs. These
-   take care of barrier requirements due to lock-free lookup.
+4. To look up the file structure given an fd, a reader must use one of
+   the fget() helpers: fget(), fget_raw(), fget_task(), fget_task_next()
+   or fdget() and friends. These take the reference and take care of
+   the barrier requirements of the lock-free lookup.
 
    An example::
 
 	struct file *file;
 
-	rcu_read_lock();
-	file = lookup_fdget_rcu(fd);
-	rcu_read_unlock();
+	file = fget(fd);
 	if (file) {
 		...
-                fput(file);
+		fput(file);
 	}
 	....
 
+   fdget() skips the reference when the file descriptor table isn't
+   shared, see the comment above __fget_light() for the rules that come
+   with that. Under files->file_lock a file can be looked up without a
+   reference with files_lookup_fd_locked() as long as the lock is held.
+
 5. Since both fdtable and file structures can be looked up
    lock-free, they must be installed using rcu_assign_pointer()
    API. If they are looked up lock-free, rcu_dereference()
    must be used. However it is advisable to use files_fdtable()
-   and lookup_fdget_rcu()/files_lookup_fdget_rcu() which take care of these
-   issues.
+   and the fget() helpers which take care of these issues.
 
 6. While updating, the fdtable pointer must be looked up while
    holding files->file_lock. If ->file_lock is dropped, then
@@ -105,15 +108,24 @@ the fdtable structure -
    Since locate_fd() can drop ->file_lock (and reacquire ->file_lock),
    the fdtable pointer (fdt) must be loaded after locate_fd().
 
-On newer kernels rcu based file lookup has been switched to rely on
-SLAB_TYPESAFE_BY_RCU instead of call_rcu(). It isn't sufficient anymore
-to just acquire a reference to the file in question under rcu using
-atomic_long_inc_not_zero() since the file might have already been
-recycled and someone else might have bumped the reference. In other
-words, callers might see reference count bumps from newer users. For
-this is reason it is necessary to verify that the pointer is the same
-before and after the reference count increment. This pattern can be seen
-in get_file_rcu() and __files_get_rcu().
+Files are allocated from a SLAB_TYPESAFE_BY_RCU cache since commit
+0ede61d8589c ("file: convert to SLAB_TYPESAFE_BY_RCU"). Freeing a file
+doesn't wait for a grace period anymore. The memory can be handed out
+again right away and only the type of the object is stable under
+rcu_read_lock(). So it isn't sufficient to take a reference on the file
+found in a descriptor slot. The file might have been closed, freed and
+recycled in the meantime and the reference lands on whoever owns the
+object now. The lock-free lookup in __fget_files_rcu() and
+__get_file_rcu() therefore:
+
+(1) loads the pointer from the slot and takes a reference with
+    file_ref_get(), which fails if the file is dead,
+
+(2) reloads the pointer and compares it against the earlier load, if they
+    differ the file was recycled and the reference is dropped again, and
+
+(3) returns the reloaded pointer so that everything the caller reads
+    from the file depends on the reload.
 
 In addition, it isn't possible to access or check fields in struct file
 without first acquiring a reference on it under rcu lookup. Not doing

-- 
2.53.0