Documentation/filesystems/caching/netfs-api.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/caching/netfs-api.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/caching/netfs-api.rst
Extension
.rst
Size
18189 bytes
Lines
453
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

==============================
Network Filesystem Caching API
==============================

Fscache provides an API by which a network filesystem can make use of local
caching facilities.  The API is arranged around a number of principles:

 (1) A cache is logically organised into volumes and data storage objects
     within those volumes.

 (2) Volumes and data storage objects are represented by various types of
     cookie.

 (3) Cookies have keys that distinguish them from their peers.

 (4) Cookies have coherency data that allows a cache to determine if the
     cached data is still valid.

 (5) I/O is done asynchronously where possible.

This API is used by::

	#include <linux/fscache.h>.

.. This document contains the following sections:

	 (1) Overview
	 (2) Volume registration
	 (3) Data file registration
	 (4) Declaring a cookie to be in use
	 (5) Resizing a data file (truncation)
	 (6) Data I/O API
	 (7) Data file coherency
	 (8) Data file invalidation
	 (9) Write back resource management
	(10) Caching of local modifications
	(11) Page release and invalidation


Overview
========

The fscache hierarchy is organised on two levels from a network filesystem's
point of view.  The upper level represents "volumes" and the lower level
represents "data storage objects".  These are represented by two types of
cookie, hereafter referred to as "volume cookies" and "cookies".

A network filesystem acquires a volume cookie for a volume using a volume key,
which represents all the information that defines that volume (e.g. cell name
or server address, volume ID or share name).  This must be rendered as a
printable string that can be used as a directory name (ie. no '/' characters
and shouldn't begin with a '.').  The maximum name length is one less than the
maximum size of a filename component (allowing the cache backend one char for
its own purposes).

A filesystem would typically have a volume cookie for each superblock.

The filesystem then acquires a cookie for each file within that volume using an
object key.  Object keys are binary blobs and only need to be unique within
their parent volume.  The cache backend is responsible for rendering the binary
blob into something it can use and may employ hash tables, trees or whatever to
improve its ability to find an object.  This is transparent to the network
filesystem.

A filesystem would typically have a cookie for each inode, and would acquire it
in iget and relinquish it when evicting the cookie.

Once it has a cookie, the filesystem needs to mark the cookie as being in use.

Annotation

Implementation Notes