linux/Documentation/filesystems
Linus Torvalds 7cd122b552 Some filesystems use a kinda-sorta controlled dentry refcount leak to pin
dentries of created objects in dcache (and undo it when removing those).
 Reference is grabbed and not released, but it's not actually _stored_
 anywhere.  That works, but it's hard to follow and verify; among other
 things, we have no way to tell _which_ of the increments is intended
 to be an unpaired one.  Worse, on removal we need to decide whether
 the reference had already been dropped, which can be non-trivial if
 that removal is on umount and we need to figure out if this dentry is
 pinned due to e.g. unlink() not done.  Usually that is handled by using
 kill_litter_super() as ->kill_sb(), but there are open-coded special
 cases of the same (consider e.g. /proc/self).
 
 Things get simpler if we introduce a new dentry flag (DCACHE_PERSISTENT)
 marking those "leaked" dentries.  Having it set claims responsibility
 for +1 in refcount.
 
 The end result this series is aiming for:
 
 * get these unbalanced dget() and dput() replaced with new primitives that
   would, in addition to adjusting refcount, set and clear persistency flag.
 * instead of having kill_litter_super() mess with removing the remaining
   "leaked" references (e.g. for all tmpfs files that hadn't been removed
   prior to umount), have the regular shrink_dcache_for_umount() strip
   DCACHE_PERSISTENT of all dentries, dropping the corresponding
   reference if it had been set.  After that kill_litter_super() becomes
   an equivalent of kill_anon_super().
 
 Doing that in a single step is not feasible - it would affect too many places
 in too many filesystems.  It has to be split into a series.
 
 This work has really started early in 2024; quite a few preliminary pieces
 have already gone into mainline.  This chunk is finally getting to the
 meat of that stuff - infrastructure and most of the conversions to it.
 
 Some pieces are still sitting in the local branches, but the bulk of
 that stuff is here.
 
 Signed-off-by: Al Viro <viro@zeniv.linux.org.uk>
 -----BEGIN PGP SIGNATURE-----
 
 iHUEABYKAB0WIQQqUNBr3gm4hGXdBJlZ7Krx/gZQ6wUCaTEq1wAKCRBZ7Krx/gZQ
 643uAQC1rRslhw5l7OjxEpIYbGG4M+QaadN4Nf5Sr2SuTRaPJQD/W4oj/u4C2eCw
 Dd3q071tqyvm/PXNgN2EEnIaxlFUlwc=
 =rKq+
 -----END PGP SIGNATURE-----

Merge tag 'pull-persistency' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs

Pull persistent dentry infrastructure and conversion from Al Viro:
 "Some filesystems use a kinda-sorta controlled dentry refcount leak to
  pin dentries of created objects in dcache (and undo it when removing
  those). A reference is grabbed and not released, but it's not actually
  _stored_ anywhere.

  That works, but it's hard to follow and verify; among other things, we
  have no way to tell _which_ of the increments is intended to be an
  unpaired one. Worse, on removal we need to decide whether the
  reference had already been dropped, which can be non-trivial if that
  removal is on umount and we need to figure out if this dentry is
  pinned due to e.g. unlink() not done. Usually that is handled by using
  kill_litter_super() as ->kill_sb(), but there are open-coded special
  cases of the same (consider e.g. /proc/self).

  Things get simpler if we introduce a new dentry flag
  (DCACHE_PERSISTENT) marking those "leaked" dentries. Having it set
  claims responsibility for +1 in refcount.

  The end result this series is aiming for:

   - get these unbalanced dget() and dput() replaced with new primitives
     that would, in addition to adjusting refcount, set and clear
     persistency flag.

   - instead of having kill_litter_super() mess with removing the
     remaining "leaked" references (e.g. for all tmpfs files that hadn't
     been removed prior to umount), have the regular
     shrink_dcache_for_umount() strip DCACHE_PERSISTENT of all dentries,
     dropping the corresponding reference if it had been set. After that
     kill_litter_super() becomes an equivalent of kill_anon_super().

  Doing that in a single step is not feasible - it would affect too many
  places in too many filesystems. It has to be split into a series.

  This work has really started early in 2024; quite a few preliminary
  pieces have already gone into mainline. This chunk is finally getting
  to the meat of that stuff - infrastructure and most of the conversions
  to it.

  Some pieces are still sitting in the local branches, but the bulk of
  that stuff is here"

* tag 'pull-persistency' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs: (54 commits)
  d_make_discardable(): warn if given a non-persistent dentry
  kill securityfs_recursive_remove()
  convert securityfs
  get rid of kill_litter_super()
  convert rust_binderfs
  convert nfsctl
  convert rpc_pipefs
  convert hypfs
  hypfs: swich hypfs_create_u64() to returning int
  hypfs: switch hypfs_create_str() to returning int
  hypfs: don't pin dentries twice
  convert gadgetfs
  gadgetfs: switch to simple_remove_by_name()
  convert functionfs
  functionfs: switch to simple_remove_by_name()
  functionfs: fix the open/removal races
  functionfs: need to cancel ->reset_work in ->kill_sb()
  functionfs: don't bother with ffs->ref in ffs_data_{opened,closed}()
  functionfs: don't abuse ffs_data_closed() on fs shutdown
  convert selinuxfs
  ...
2025-12-05 14:36:21 -08:00
..
caching doc: correcting the debug path for cachefiles 2024-10-24 13:50:27 +02:00
ext4 Documentation: ext4: Document casefold and encrypt flags 2025-11-26 17:13:34 -05:00
fuse Documentation: fuse: Consolidate FUSE docs into its own subdirectory 2025-08-27 14:29:43 +02:00
gfs2 Documentation: gfs2: Consolidate GFS2 docs into its own subdirectory 2025-10-31 21:00:43 +00:00
iomap fs, iomap: remove IOCB_DIO_CALLER_COMP 2025-11-25 10:22:18 +01:00
nfs nfsd: disallow file locking and delegations for NFSv4 reexport 2025-03-10 09:11:08 -04:00
smb cifs: add documentation for smbdirect setup 2025-06-05 10:20:48 -05:00
spufs
xfs xfs: new code for v6.19 2025-12-03 20:19:38 -08:00
9p.rst 9p update for 6.15-rc1 2025-04-03 15:35:46 -07:00
adfs.rst
affs.rst
afs.rst
api-summary.rst doc: split buffer.rst out of api-summary.rst 2024-05-05 17:53:40 -07:00
autofs-mount-control.rst
autofs.rst Documentation: filesystems: update filename extensions 2024-11-22 10:31:04 -07:00
automount-support.rst
befs.rst
bfs.rst
btrfs.rst MAINTAINERS: remove links to obsolete btrfs.wiki.kernel.org 2023-09-08 14:21:27 +02:00
buffer.rst doc: split buffer.rst out of api-summary.rst 2024-05-05 17:53:40 -07:00
ceph.rst doc: ceph: update userspace command to get CephFS metadata 2024-05-23 10:35:47 +02:00
coda.rst documentation/filesystems: fix spelling mistakes 2025-02-10 10:42:28 -07:00
configfs.rst
cramfs.rst
dax.rst doc: Remove misleading reference to brd in dax.rst 2025-06-25 12:49:29 -06:00
debugfs.rst docs: debugfs: do not recommend debugfs_remove_recursive 2025-04-30 19:11:04 +02:00
devpts.rst
directory-locking.rst Docs: typos/spelling 2024-05-02 10:02:29 -06:00
dlmfs.rst Documentation: filesystems: update filename extensions 2024-11-22 10:31:04 -07:00
dnotify.rst
ecryptfs.rst
efivarfs.rst Documentation: Mark the 'efivars' sysfs interface as removed 2024-04-13 10:33:02 +02:00
erofs.rst Documentation: Fix filesystems typos 2025-08-18 10:31:19 -06:00
ext2.rst
ext3.rst
f2fs.rst Documentation: f2fs: Reword title 2025-08-28 00:09:02 +00:00
fiemap.rst fiemap: use kernel-doc includes in fiemap docbook 2024-12-22 11:29:50 +01:00
files.rst docs: filesystems: fix typo in docs 2024-02-09 10:37:20 +01:00
fscrypt.rst fscrypt: Drop obsolete recommendation to enable optimized POLYVAL 2025-11-11 11:03:39 -08:00
fsverity.rst fsverity: Switch from crypto_shash to SHA-2 library 2025-07-14 11:29:32 -07:00
hfs.rst
hfsplus.rst
hpfs.rst Documentation: Fix filesystems typos 2025-08-18 10:31:19 -06:00
idmappings.rst doc: correcting two prefix errors in idmappings.rst 2025-03-05 11:54:18 +01:00
index.rst Documentation: gfs2: Consolidate GFS2 docs into its own subdirectory 2025-10-31 21:00:43 +00:00
inotify.rst
isofs.rst
journalling.rst jbd2: remove unused transaction->t_private_list 2025-02-10 07:48:24 -05:00
locking.rst block: switch ->getgeo() to struct gendisk 2025-08-13 02:59:29 -04:00
locks.rst
mount_api.rst change the calling conventions for vfs_parse_fs_string() 2025-09-04 15:20:51 -04:00
multigrain-ts.rst Documentation: add a new file documenting multigrain timestamps 2024-10-10 10:20:52 +02:00
netfs_library.rst fs/netfs: remove unused flag NETFS_SREQ_SEEK_DATA_READ 2025-05-21 14:34:37 +02:00
nilfs2.rst
ntfs3.rst
ocfs2-online-filecheck.rst Documentation: ocfs2: Properly reindent filecheck operations list 2025-08-29 15:50:50 -06:00
ocfs2.rst
omfs.rst
orangefs.rst
overlayfs.rst overlayfs.rst: fix typos 2025-07-15 13:53:46 -06:00
path-lookup.rst Documentation: filesystems: update filename extensions 2024-11-22 10:31:04 -07:00
path-lookup.txt Documentation: filesystems: update filename extensions 2024-11-22 10:31:04 -07:00
porting.rst Some filesystems use a kinda-sorta controlled dentry refcount leak to pin 2025-12-05 14:36:21 -08:00
proc.rst mm: introduce VM_MAYBE_GUARD and make visible in /proc/$pid/smaps 2025-11-20 13:43:58 -08:00
propagate_umount.txt docs: fix trailing whitespace error and remove repeated words in propagate_umount.txt 2025-08-21 12:49:01 -06:00
qnx6.rst
quota.rst
ramfs-rootfs-initramfs.rst docs: replace broken links in ramfs-rootfs-initramfs docs 2025-10-29 16:19:26 -06:00
relay.rst - The 3 patch series "hung_task: extend blocking task stacktrace dump to 2025-05-31 19:12:53 -07:00
resctrl.rst fs/resctrl: Update bit_usage to reflect io_alloc 2025-11-22 14:30:34 +01:00
romfs.rst
seq_file.rst
sharedsubtree.rst Documentation: sharedsubtree: Convert notes to note directive 2025-08-29 16:40:01 -06:00
splice.rst
squashfs.rst Documentation: update the Squashfs filesystem documentation 2025-01-24 22:47:21 -08:00
sysfs.rst It has been a relatively busy cycle in docsland, with changes all over: 2025-10-03 17:16:13 -07:00
tmpfs.rst docs: tmpfs: Add casefold options 2024-10-28 13:36:55 +01:00
ubifs-authentication.rst Documentation: treewide: Replace remaining spinics links with lore 2025-06-21 14:20:51 -06:00
ubifs.rst
udf.rst
vfat.rst
vfs.rst doc: update porting, vfs documentation for mmap_prepare actions 2025-11-16 17:28:13 -08:00
virtiofs.rst
zonefs.rst