Merge branch 'mauro' into docs-next

pty

===

See Documentation/filesystems/devpts.txt.

See Documentation/filesystems/devpts.rst.

randomize_va_space

.. SPDX-License-Identifier: GPL-2.0

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

Automount Support

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

Support is available for filesystems that wish to do automounting

support (such as kAFS which can be found in fs/afs/ and NFS in

fs/nfs/). This facility includes allowing in-kernel mounts to be

also be requested by userspace.

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

IN-KERNEL AUTOMOUNTING

In-Kernel Automounting

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

See section "Mount Traps" of  Documentation/filesystems/autofs.rst

Then from userspace, you can just do something like:

Then from userspace, you can just do something like::

	[root@andromeda root]# mount -t afs \#root.afs. /afs

	[root@andromeda root]# ls /afs

	[root@andromeda root]# ls /afs/cambridge/afsdoc/

	ChangeLog  html  LICENSE  pdf  RELNOTES-1.2.2

And then if you look in the mountpoint catalogue, you'll see something like:

And then if you look in the mountpoint catalogue, you'll see something like::

	[root@andromeda root]# cat /proc/mounts

	...

	#afsdoc. /afs/cambridge.redhat.com/afsdoc afs rw 0 0

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

AUTOMATIC MOUNTPOINT EXPIRY

Automatic Mountpoint Expiry

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

Automatic expiration of mountpoints is easy, provided you've mounted the

     hung.

 (2) When a new mountpoint is created in the ->d_automount method, add

     the mnt to the list using mnt_set_expiry()

     the mnt to the list using mnt_set_expiry()::

             mnt_set_expiry(newmnt, &afs_vfsmounts);

 (3) When you want mountpoints to be expired, call mark_mounts_for_expiry()

same expiration list.

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

USERSPACE DRIVEN EXPIRY

Userspace Driven Expiry

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

As an alternative, it is possible for userspace to request expiry of any

.. SPDX-License-Identifier: GPL-2.0

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

			  FS-CACHE CACHE BACKEND API

FS-Cache Cache backend API

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

The FS-Cache system provides an API by which actual caches can be supplied to

This API is declared in <linux/fscache-cache.h>.

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

INITIALISING AND REGISTERING A CACHE

Initialising and Registering a Cache

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

To start off, a cache definition must be initialised and registered for each

cache the backend wants to make available.  For instance, CacheFS does this in

the fill_super() operation on mounting.

The cache definition (struct fscache_cache) should be initialised by calling:

The cache definition (struct fscache_cache) should be initialised by calling::

	void fscache_init_cache(struct fscache_cache *cache,

				struct fscache_cache_ops *ops,

Where:

 (*) "cache" is a pointer to the cache definition;

   * "cache" is a pointer to the cache definition;

 (*) "ops" is a pointer to the table of operations that the backend supports on

   * "ops" is a pointer to the table of operations that the backend supports on

     this cache; and

 (*) "idfmt" is a format and printf-style arguments for constructing a label

   * "idfmt" is a format and printf-style arguments for constructing a label

     for the cache.

The cache should then be registered with FS-Cache by passing a pointer to the

previously initialised cache definition to:

previously initialised cache definition to::

	int fscache_add_cache(struct fscache_cache *cache,

			      struct fscache_object *fsdef,

Two extra arguments should also be supplied:

 (*) "fsdef" which should point to the object representation for the FS-Cache

   * "fsdef" which should point to the object representation for the FS-Cache

     master index in this cache.  Netfs primary index entries will be created

     here.  FS-Cache keeps the caller's reference to the index object if

     successful and will release it upon withdrawal of the cache.

 (*) "tagname" which, if given, should be a text string naming this cache.  If

   * "tagname" which, if given, should be a text string naming this cache.  If

     this is NULL, the identifier will be used instead.  For CacheFS, the

     identifier is set to name the underlying block device and the tag can be

     supplied by mount.

is already in use.  0 will be returned on success.

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

UNREGISTERING A CACHE

Unregistering a Cache

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

A cache can be withdrawn from the system by calling this function with a

pointer to the cache definition:

pointer to the cache definition::

	void fscache_withdraw_cache(struct fscache_cache *cache);

In CacheFS's case, this is called by put_super().

========

SECURITY

Security

========

The cache methods are executed one of two contexts:

This is left to the cache to handle; FS-Cache makes no effort in this regard.

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

CONTROL AND STATISTICS PRESENTATION

Control and Statistics Presentation

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

The cache may present data to the outside world through FS-Cache's interfaces

and is for use by the cache as it sees fit.

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

RELEVANT DATA STRUCTURES

Relevant Data Structures

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

 (*) Index/Data file FS-Cache representation cookie:

   * Index/Data file FS-Cache representation cookie::

	struct fscache_cookie {

		struct fscache_object_def	*def;

     cache operations.

 (*) In-cache object representation:

   * In-cache object representation::

	struct fscache_object {

		int				debug_id;

     initialised by calling fscache_object_init(object).

 (*) FS-Cache operation record:

   * FS-Cache operation record::

	struct fscache_operation {

		atomic_t		usage;

     an operation needs more processing time, it should be enqueued again.

 (*) FS-Cache retrieval operation record:

   * FS-Cache retrieval operation record::

	struct fscache_retrieval {

		struct fscache_operation op;

     it sees fit.

 (*) FS-Cache storage operation record:

   * FS-Cache storage operation record::

	struct fscache_storage {

		struct fscache_operation op;

     storage.

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

CACHE OPERATIONS

Cache Operations

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

The cache backend provides FS-Cache with a table of operations that can be

performed on the denizens of the cache.  These are held in a structure of type:

	::

	    struct fscache_cache_ops

 (*) Name of cache provider [mandatory]:

   * Name of cache provider [mandatory]::

	const char *name

     the backend.

 (*) Allocate a new object [mandatory]:

   * Allocate a new object [mandatory]::

	struct fscache_object *(*alloc_object)(struct fscache_cache *cache,

					       struct fscache_cookie *cookie)

     form once lookup is complete or aborted.

 (*) Look up and create object [mandatory]:

   * Look up and create object [mandatory]::

	void (*lookup_object)(struct fscache_object *object)

     to abort the lookup of that object.

 (*) Release lookup data [mandatory]:

   * Release lookup data [mandatory]::

	void (*lookup_complete)(struct fscache_object *object)

     using to perform a lookup.

 (*) Increment object refcount [mandatory]:

   * Increment object refcount [mandatory]::

	struct fscache_object *(*grab_object)(struct fscache_object *object)

     It should return the object pointer if successful.

 (*) Lock/Unlock object [mandatory]:

   * Lock/Unlock object [mandatory]::

	void (*lock_object)(struct fscache_object *object)

	void (*unlock_object)(struct fscache_object *object)

     to schedule with the lock held, so a spinlock isn't sufficient.

 (*) Pin/Unpin object [optional]:

   * Pin/Unpin object [optional]::

	int (*pin_object)(struct fscache_object *object)

	void (*unpin_object)(struct fscache_object *object)

     enough space in the cache to permit this.

 (*) Check coherency state of an object [mandatory]:

   * Check coherency state of an object [mandatory]::

	int (*check_consistency)(struct fscache_object *object)

     if they're consistent and -ESTALE otherwise.  -ENOMEM and -ERESTARTSYS

     may also be returned.

 (*) Update object [mandatory]:

   * Update object [mandatory]::

	int (*update_object)(struct fscache_object *object)

     obtained by calling object->cookie->def->get_aux()/get_attr().

 (*) Invalidate data object [mandatory]:

   * Invalidate data object [mandatory]::

	int (*invalidate_object)(struct fscache_operation *op)

     fscache_op_complete() must be called on op before returning.

 (*) Discard object [mandatory]:

   * Discard object [mandatory]::

	void (*drop_object)(struct fscache_object *object)

     caller.  The caller will invoke the put_object() method as appropriate.

 (*) Release object reference [mandatory]:

   * Release object reference [mandatory]::

	void (*put_object)(struct fscache_object *object)

     be freed when all the references to it are released.

 (*) Synchronise a cache [mandatory]:

   * Synchronise a cache [mandatory]::

	void (*sync)(struct fscache_cache *cache)

     device.

 (*) Dissociate a cache [mandatory]:

   * Dissociate a cache [mandatory]::

	void (*dissociate_pages)(struct fscache_cache *cache)

     cache withdrawal.

 (*) Notification that the attributes on a netfs file changed [mandatory]:

   * Notification that the attributes on a netfs file changed [mandatory]::

	int (*attr_changed)(struct fscache_object *object);

     execution of this operation.

 (*) Reserve cache space for an object's data [optional]:

   * Reserve cache space for an object's data [optional]::

	int (*reserve_space)(struct fscache_object *object, loff_t size);

     size if larger than that already.

 (*) Request page be read from cache [mandatory]:

   * Request page be read from cache [mandatory]::

	int (*read_or_alloc_page)(struct fscache_retrieval *op,

				  struct page *page,

     with.  This will complete the operation when all pages are dealt with.

 (*) Request pages be read from cache [mandatory]:

   * Request pages be read from cache [mandatory]::

	int (*read_or_alloc_pages)(struct fscache_retrieval *op,

				   struct list_head *pages,

     of pages instead of one page.  Any pages on which a read operation is

     started must be added to the page cache for the specified mapping and also

     to the LRU.  Such pages must also be removed from the pages list and

     *nr_pages decremented per page.

     ``*nr_pages`` decremented per page.

     If there was an error such as -ENOMEM, then that should be returned; else

     if one or more pages couldn't be read or allocated, then -ENOBUFS should

     returned.

 (*) Request page be allocated in the cache [mandatory]:

   * Request page be allocated in the cache [mandatory]::

	int (*allocate_page)(struct fscache_retrieval *op,

			     struct page *page,

     allocated, then the netfs page should be marked and 0 returned.

 (*) Request pages be allocated in the cache [mandatory]:

   * Request pages be allocated in the cache [mandatory]::

	int (*allocate_pages)(struct fscache_retrieval *op,

			      struct list_head *pages,

     nr_pages should be treated as for the read_or_alloc_pages() method.

 (*) Request page be written to cache [mandatory]:

   * Request page be written to cache [mandatory]::

	int (*write_page)(struct fscache_storage *op,

			  struct page *page);

     appropriately.

 (*) Discard retained per-page metadata [mandatory]:

   * Discard retained per-page metadata [mandatory]::

	void (*uncache_page)(struct fscache_object *object, struct page *page)

     maintains for this page.

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

FS-CACHE UTILITIES

FS-Cache Utilities

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

FS-Cache provides some utilities that a cache backend may make use of:

 (*) Note occurrence of an I/O error in a cache:

   * Note occurrence of an I/O error in a cache::

	void fscache_io_error(struct fscache_cache *cache)

     This does not actually withdraw the cache.  That must be done separately.

 (*) Invoke the retrieval I/O completion function:

   * Invoke the retrieval I/O completion function::

	void fscache_end_io(struct fscache_retrieval *op, struct page *page,

			    int error);

     error value should be 0 if successful and an error otherwise.

 (*) Record that one or more pages being retrieved or allocated have been dealt

     with:

   * Record that one or more pages being retrieved or allocated have been dealt

     with::

	void fscache_retrieval_complete(struct fscache_retrieval *op,

					int n_pages);

     completed.

 (*) Record operation completion:

   * Record operation completion::

	void fscache_op_complete(struct fscache_operation *op);

     one or more pending operations to start running.

 (*) Set highest store limit:

   * Set highest store limit::

	void fscache_set_store_limit(struct fscache_object *object,

				     loff_t i_size);

     rejected by fscache_read_alloc_page() and co with -ENOBUFS.

 (*) Mark pages as being cached:

   * Mark pages as being cached::

	void fscache_mark_pages_cached(struct fscache_retrieval *op,

				       struct pagevec *pagevec);

     the netfs must call fscache_uncache_page() to unmark the pages.

 (*) Perform coherency check on an object:

   * Perform coherency check on an object::

	enum fscache_checkaux fscache_check_aux(struct fscache_object *object,

						const void *data,

     One of three values will be returned:

	(*) FSCACHE_CHECKAUX_OKAY

	FSCACHE_CHECKAUX_OKAY

	    The coherency data indicates the object is valid as is.

	(*) FSCACHE_CHECKAUX_NEEDS_UPDATE

	FSCACHE_CHECKAUX_NEEDS_UPDATE

	    The coherency data needs updating, but otherwise the object is

	    valid.

	(*) FSCACHE_CHECKAUX_OBSOLETE

	FSCACHE_CHECKAUX_OBSOLETE

	    The coherency data indicates that the object is obsolete and should

	    be discarded.

 (*) Initialise a freshly allocated object:

   * Initialise a freshly allocated object::

	void fscache_object_init(struct fscache_object *object);

     This initialises all the fields in an object representation.

 (*) Indicate the destruction of an object:

   * Indicate the destruction of an object::

	void fscache_object_destroyed(struct fscache_cache *cache);

     all the objects.

 (*) Indicate negative lookup on an object:

   * Indicate negative lookup on an object::

	void fscache_object_lookup_negative(struct fscache_object *object);

     significant - all subsequent calls are ignored.

 (*) Indicate an object has been obtained:

   * Indicate an object has been obtained::

	void fscache_obtained_object(struct fscache_object *object);

        (2) that writes may now proceed against this object.

 (*) Indicate that object lookup failed:

   * Indicate that object lookup failed::

	void fscache_object_lookup_error(struct fscache_object *object);

     as possible.

 (*) Indicate that a stale object was found and discarded:

   * Indicate that a stale object was found and discarded::

	void fscache_object_retrying_stale(struct fscache_object *object);

     discarded from the cache and the lookup will be performed again.

 (*) Indicate that the caching backend killed an object:

   * Indicate that the caching backend killed an object::

	void fscache_object_mark_killed(struct fscache_object *object,

					enum fscache_why_object_killed why);

     This is called to indicate that the cache backend preemptively killed an

     object.  The why parameter should be set to indicate the reason:

	FSCACHE_OBJECT_IS_STALE - the object was stale and needs discarding.

	FSCACHE_OBJECT_NO_SPACE - there was insufficient cache space

	FSCACHE_OBJECT_WAS_RETIRED - the object was retired when relinquished.

	FSCACHE_OBJECT_WAS_CULLED - the object was culled to make space.

	FSCACHE_OBJECT_IS_STALE

	    - the object was stale and needs discarding.

	FSCACHE_OBJECT_NO_SPACE

	    - there was insufficient cache space

	FSCACHE_OBJECT_WAS_RETIRED

	    - the object was retired when relinquished.

	FSCACHE_OBJECT_WAS_CULLED

	    - the object was culled to make space.

 (*) Get and release references on a retrieval record:

   * Get and release references on a retrieval record::

	void fscache_get_retrieval(struct fscache_retrieval *op);

	void fscache_put_retrieval(struct fscache_retrieval *op);

     asynchronous data retrieval and block allocation.

 (*) Enqueue a retrieval record for processing.

   * Enqueue a retrieval record for processing::

	void fscache_enqueue_retrieval(struct fscache_retrieval *op);

     within the callback function.

 (*) List of object state names:

   * List of object state names::

	const char *fscache_object_states[];