docs: fs: convert docs without extension to ReST

=================

Directory Locking

=================

Locking scheme used for directory operations is based on two

kinds of locks - per-inode (->i_rwsem) and per-filesystem

(->s_vfs_rename_mutex).

case) shared.

5) link creation.  Locking rules:

	* lock parent

	* check that source is not a directory

	* lock source

	* call the method.

All locks are exclusive.

6) cross-directory rename.  The trickiest in the whole bunch.  Locking

rules:

	* lock the filesystem

	* lock parents in "ancestors first" order.

	* find source and target.

	* If the target exists, lock it.  If the source is a non-directory,

	  lock it.  If we need to lock both, do so in inode pointer order.

	* call the method.

All ->i_rwsem are taken exclusive.  Again, we might get away with locking

the the source (and target in exchange case) shared.

If no directory is its own ancestor, the scheme above is deadlock-free.

Proof:

	First of all, at any moment we have a partial ordering of the

   path-lookup

   api-summary

   splice

   locking

   directory-locking

Filesystem support layers

=========================

=======

Locking

=======

The text below describes the locking rules for VFS-related methods.

It is (believed to be) up-to-date. *Please*, if you change anything in

prototypes or locking protocols - update this file. And update the relevant

etc. At the very least, put the list of dubious cases in the end of this file.

Don't turn it into log - maintainers of out-of-the-tree code are supposed to

be able to use diff(1).

Thing currently missing here: socket operations. Alexey?

--------------------------- dentry_operations --------------------------

prototypes:

dentry_operations

=================

prototypes::

	int (*d_revalidate)(struct dentry *, unsigned int);

	int (*d_weak_revalidate)(struct dentry *, unsigned int);

	int (*d_hash)(const struct dentry *, struct qstr *);

	struct dentry *(*d_real)(struct dentry *, const struct inode *);

locking rules:

		rename_lock	->d_lock	may block	rcu-walk

================== ===========	========	==============	========

ops		   rename_lock	->d_lock	may block	rcu-walk

================== ===========	========	==============	========

d_revalidate:	   no		no		yes (ref-walk)	maybe

d_weak_revalidate: no		no		yes	 	no

d_hash		   no		no		no		maybe

d_automount:	   no		no		yes		no

d_manage:	   no		no		yes (ref-walk)	maybe

d_real		   no		no		yes 		no

================== ===========	========	==============	========

inode_operations

================

prototypes::

--------------------------- inode_operations --------------------------- 

prototypes:

	int (*create) (struct inode *,struct dentry *,umode_t, bool);

	struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);

	int (*link) (struct dentry *,struct inode *,struct dentry *);

locking rules:

	all may block

		i_rwsem(inode)

============	=============================================

ops		i_rwsem(inode)

============	=============================================

lookup:		shared

create:		exclusive

link:		exclusive (both)

update_time:	no

atomic_open:	exclusive

tmpfile:	no

============	=============================================

	Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem

	exclusive on victim.

	cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.

See Documentation/filesystems/directory-locking for more detailed discussion

See Documentation/filesystems/directory-locking.rst for more detailed discussion

of the locking scheme for directory operations.

----------------------- xattr_handler operations -----------------------

prototypes:

xattr_handler operations

========================

prototypes::

	bool (*list)(struct dentry *dentry);

	int (*get)(const struct xattr_handler *handler, struct dentry *dentry,

		   struct inode *inode, const char *name, void *buffer,

locking rules:

	all may block

		i_rwsem(inode)

=====		==============

ops		i_rwsem(inode)

=====		==============

list:		no

get:		no

set:		exclusive

=====		==============

super_operations

================

prototypes::

--------------------------- super_operations ---------------------------

prototypes:

	struct inode *(*alloc_inode)(struct super_block *sb);

	void (*free_inode)(struct inode *);

	void (*destroy_inode)(struct inode *);

locking rules:

	All may block [not true, see below]

			s_umount

======================	============	========================

ops			s_umount	note

======================	============	========================

alloc_inode:

free_inode:				called from RCU callback

destroy_inode:

quota_read:		no		(see below)

quota_write:		no		(see below)

bdev_try_to_free_page:	no		(see below)

======================	============	========================

->statfs() has s_umount (shared) when called by ustat(2) (native or

compat), but that's an accident of bad API; s_umount is used to pin

identify the superblock.  Everything else (statfs(), fstatfs(), etc.)

doesn't hold it when calling ->statfs() - superblock is pinned down

by resolving the pathname passed to syscall.

->quota_read() and ->quota_write() functions are both guaranteed to

be the only ones operating on the quota file by the quota code (via

dqio_sem) (unless an admin really wants to screw up something and

writes to quota files with quotas on). For other details about locking

see also dquot_operations section.

->bdev_try_to_free_page is called from the ->releasepage handler of

the block device inode.  See there for more details.

--------------------------- file_system_type ---------------------------

prototypes:

file_system_type

================

prototypes::

	struct dentry *(*mount) (struct file_system_type *, int,

		       const char *, void *);

	void (*kill_sb) (struct super_block *);

locking rules:

		may block

=======		=========

ops		may block

=======		=========

mount		yes

kill_sb		yes

=======		=========

->mount() returns ERR_PTR or the root dentry; its superblock should be locked

on return.

->kill_sb() takes a write-locked superblock, does all shutdown work on it,

unlocks and drops the reference.

--------------------------- address_space_operations --------------------------

prototypes:

address_space_operations

========================

prototypes::

	int (*writepage)(struct page *page, struct writeback_control *wbc);

	int (*readpage)(struct file *, struct page *);

	int (*writepages)(struct address_space *, struct writeback_control *);

locking rules:

	All except set_page_dirty and freepage may block

			PageLocked(page)	i_rwsem

======================	======================== =========

ops			PageLocked(page)	 i_rwsem

======================	======================== =========

writepage:		yes, unlocks (see below)

readpage:		yes, unlocks

writepages:

error_remove_page:	yes

swap_activate:		no

swap_deactivate:	no

======================	======================== =========

->write_begin(), ->write_end() and ->readpage() may be called from

the request handler (/dev/loop).

->writepages() is used for periodic writeback and for syscall-initiated

sync operations.  The address_space should start I/O against at least

*nr_to_write pages.  *nr_to_write must be decremented for each page which is

written.  The address_space implementation may write more (or less) pages

than *nr_to_write asks for, but it should try to be reasonably close.  If

nr_to_write is NULL, all dirty pages must be written.

``*nr_to_write`` pages.  ``*nr_to_write`` must be decremented for each page

which is written.  The address_space implementation may write more (or less)

pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.

If nr_to_write is NULL, all dirty pages must be written.

writepages should _only_ write pages which are present on

mapping->io_pages.

->swap_deactivate() will be called in the sys_swapoff()

path after ->swap_activate() returned success.

----------------------- file_lock_operations ------------------------------

prototypes:

file_lock_operations

====================

prototypes::

	void (*fl_copy_lock)(struct file_lock *, struct file_lock *);

	void (*fl_release_private)(struct file_lock *);

locking rules:

			inode->i_lock	may block

===================	=============	=========

ops			inode->i_lock	may block

===================	=============	=========

fl_copy_lock:		yes		no

fl_release_private:	maybe		maybe[1]

fl_release_private:	maybe		maybe[1]_

===================	=============	=========

[1]:	->fl_release_private for flock or POSIX locks is currently allowed

.. [1]:

   ->fl_release_private for flock or POSIX locks is currently allowed

   to block. Leases however can still be freed while the i_lock is held and

   so fl_release_private called on a lease should not block.

----------------------- lock_manager_operations ---------------------------

prototypes:

lock_manager_operations

=======================

prototypes::

	void (*lm_notify)(struct file_lock *);  /* unblock callback */

	int (*lm_grant)(struct file_lock *, struct file_lock *, int);

	void (*lm_break)(struct file_lock *); /* break_lease callback */

locking rules:

			inode->i_lock	blocked_lock_lock	may block

==========		=============	=================	=========

ops			inode->i_lock	blocked_lock_lock	may block

==========		=============	=================	=========

lm_notify:		yes		yes			no

lm_grant:		no		no			no

lm_break:		yes		no			no

lm_change		yes		no			no

==========		=============	=================	=========

buffer_head

===========

prototypes::

--------------------------- buffer_head -----------------------------------

prototypes:

	void (*b_end_io)(struct buffer_head *bh, int uptodate);

locking rules:

called from interrupts. In other words, extreme care is needed here.

bh is locked, but that's all warranties we have here. Currently only RAID1,

highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices

call this method upon the IO completion.

--------------------------- block_device_operations -----------------------

prototypes:

block_device_operations

=======================

prototypes::

	int (*open) (struct block_device *, fmode_t);

	int (*release) (struct gendisk *, fmode_t);

	int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);

	void (*swap_slot_free_notify) (struct block_device *, unsigned long);

locking rules:

			bd_mutex

======================= ===================

ops			bd_mutex

======================= ===================

open:			yes

release:		yes

ioctl:			no

revalidate_disk:	no

getgeo:			no

swap_slot_free_notify:	no	(see below)

======================= ===================

media_changed, unlock_native_capacity and revalidate_disk are called only from

check_disk_change().

held.

--------------------------- file_operations -------------------------------

prototypes:

file_operations

===============

prototypes::

	loff_t (*llseek) (struct file *, loff_t, int);

	ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);

	ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);

			size_t, unsigned int);

	int (*setlease)(struct file *, long, struct file_lock **, void **);

	long (*fallocate)(struct file *, int, loff_t, loff_t);

};

locking rules:

	All may block.

the lease within the individual filesystem to record the result of the

operation

--------------------------- dquot_operations -------------------------------

prototypes:

dquot_operations

================

prototypes::

	int (*write_dquot) (struct dquot *);

	int (*acquire_dquot) (struct dquot *);

	int (*release_dquot) (struct dquot *);

What filesystem should expect from the generic quota functions:

		FS recursion	Held locks when called

==============	============	=========================

ops		FS recursion	Held locks when called

==============	============	=========================

write_dquot:	yes		dqonoff_sem or dqptr_sem

acquire_dquot:	yes		dqonoff_sem or dqptr_sem

release_dquot:	yes		dqonoff_sem or dqptr_sem

mark_dirty:	no		-

write_info:	yes		dqonoff_sem

==============	============	=========================

FS recursion means calling ->quota_read() and ->quota_write() from superblock

operations.

More details about quota locking can be found in fs/dquot.c.

--------------------------- vm_operations_struct -----------------------------

prototypes:

vm_operations_struct

====================

prototypes::

	void (*open)(struct vm_area_struct*);

	void (*close)(struct vm_area_struct*);

	vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);

	int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);

locking rules:

		mmap_sem	PageLocked(page)

=============	========	===========================

ops		mmap_sem	PageLocked(page)

=============	========	===========================

open:		yes

close:		yes

fault:		yes		can return with page locked

page_mkwrite:	yes		can return with page locked

pfn_mkwrite:	yes

access:		yes

=============	========	===========================

->fault() is called when a previously not present pte is about

to be faulted in. The filesystem must find and return the page associated

/proc/pid/mem or ptrace.  This function is needed only for

VM_IO | VM_PFNMAP VMAs.

================================================================================

--------------------------------------------------------------------------------

			Dubious stuff

(if you break something or notice that it is broken and do not fix it yourself

:orphan:

Making Filesystems Exportable

=============================

for the object.  This leads to two related but distinct features of

the dcache that are not needed for normal filesystem access.

1/ The dcache must sometimes contain objects that are not part of the

1. The dcache must sometimes contain objects that are not part of the

   proper prefix. i.e that are not connected to the root.

2/ The dcache must be prepared for a newly found (via ->lookup) directory

2. The dcache must be prepared for a newly found (via ->lookup) directory

   to already have a (non-connected) dentry, and must be able to move

   that dentry into place (based on the parent and name in the

   ->lookup).   This is particularly needed for directories as

To implement these features, the dcache has:

a/ A dentry flag DCACHE_DISCONNECTED which is set on

a. A dentry flag DCACHE_DISCONNECTED which is set on

   any dentry that might not be part of the proper prefix.

   This is set when anonymous dentries are created, and cleared when a

   dentry is noticed to be a child of a dentry which is in the proper

   dentries.  That guarantees that we won't need to hunt them down upon

   umount.

b/ A primitive for creation of secondary roots - d_obtain_root(inode).

b. A primitive for creation of secondary roots - d_obtain_root(inode).

   Those do _not_ bear DCACHE_DISCONNECTED.  They are placed on the

   per-superblock list (->s_roots), so they can be located at umount

   time for eviction purposes.

c/ Helper routines to allocate anonymous dentries, and to help attach

c. Helper routines to allocate anonymous dentries, and to help attach

   loose directory dentries at lookup time. They are:

    d_obtain_alias(inode) will return a dentry for the given inode.

      If the inode already has a dentry, one of those is returned.

      If it doesn't, a new anonymous (IS_ROOT and

      DCACHE_DISCONNECTED) dentry is allocated and attached.

      In the case of a directory, care is taken that only one dentry

      can ever be attached.

    d_splice_alias(inode, dentry) will introduce a new dentry into the tree;

      either the passed-in dentry or a preexisting alias for the given inode

      (such as an anonymous one created by d_obtain_alias), if appropriate.

For a filesystem to be exportable it must:

   1/ provide the filehandle fragment routines described below.

   2/ make sure that d_splice_alias is used rather than d_add

   1. provide the filehandle fragment routines described below.

   2. make sure that d_splice_alias is used rather than d_add

      when ->lookup finds an inode for a given parent and name.

      If inode is NULL, d_splice_alias(inode, dentry) is equivalent to

      If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::

		d_add(dentry, inode), NULL

      Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)

      Typically the ->lookup routine will simply end with a:

      Typically the ->lookup routine will simply end with a::

		return d_splice_alias(inode, dentry);

	}

VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on

are called from a process context.  Filesystem locking is described in

the document Documentation/filesystems/Locking.

the document Documentation/filesystems/locking.rst.

Directory Entry Cache (dcache)