General Filesystem Caching

개요와 투명한 캐시 경로

FS-Cache는 네트워크 파일시스템용 범용 캐시이지만 ISO9660 파일시스템 같은 다른 대상의 caching에도 사용할 수 있습니다.

FS-Cache는 NFS, AFS, 9P 같은 네트워크 파일시스템 및 netfs library와 CacheFS, CacheFiles 같은 cache backend 사이를 중재합니다. 네트워크 파일시스템은 FS-Cache에 객체와 I/O를 요청하고, FS-Cache는 선택된 backend를 통해 실제 backing store를 사용합니다.

사용자 관점에서 캐시는 투명합니다. 예를 들어 원격 server의 데이터를 NFS가 제공하고, NFS는 VFS에 파일을 노출하는 동시에 FS-Cache를 통해 CacheFiles에 데이터를 저장합니다. CacheFiles는 Ext3 같은 로컬 파일시스템을 backing store로 사용하고 사용자 공간 `cachefilesd`가 관리 작업을 돕습니다. 프로세스는 이 중간 경로를 직접 다루지 않습니다.

FS-Cache는 netfs 파일을 열 때 전체 파일을 캐시에 먼저 내려받은 뒤 cache inode에서 page를 제공하는 방식을 사용하지 않습니다.

그 이유는 캐시 없이도 실용적으로 동작해야 하고, 접근 가능한 파일 크기가 캐시 크기에 제한되면 안 되며, mapping된 library를 포함한 열린 파일 전체 크기도 캐시 크기에 제한되면 안 되기 때문입니다.

또한 사용자가 `file` 명령처럼 파일의 작은 부분을 한 번 확인하려고 전체 파일을 내려받도록 강제해서는 안 됩니다. 대신 FS-Cache는 netfs가 요청할 때 필요한 chunk만 제공합니다.

.. SPDX-License-Identifier: GPL-2.0

==========================
General Filesystem Caching
==========================

Overview
========

This facility is a general purpose cache for network filesystems, though it
could be used for caching other things such as ISO9660 filesystems too.

FS-Cache mediates between cache backends (such as CacheFiles) and network
filesystems::

        +---------+
        |         |                                    +--------------+
        |   NFS   |--+                                 |              |
        |         |  |                             +-->|   CacheFS    |
        +---------+  |               +----------+  |   |  /dev/hda5   |
                     |               |          |  |   +--------------+
        +---------+  +-------------->|          |  |
        |         |      +-------+   |          |--+
        |   AFS   |----->|       |   | FS-Cache |
        |         |      | netfs |-->|          |--+
        +---------+  +-->|  lib  |   |          |  |
                     |   |       |   |          |  |   +--------------+
        +---------+  |   +-------+   +----------+  |   |              |
        |         |  |                             +-->|  CacheFiles  |
        |   9P    |--+                                 |  /var/cache  |
        |         |                                    +--------------+
        +---------+

Or to look at it another way, FS-Cache is a module that provides a caching
facility to a network filesystem such that the cache is transparent to the
user::

        +---------+
        |         |
        | Server  |
        |         |
        +---------+
             |                  NETWORK
        ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
             |
             |           +----------+
             V           |          |
        +---------+      |          |
        |         |      |          |
        |   NFS   |----->| FS-Cache |
        |         |      |          |--+
        +---------+      |          |  |   +--------------+   +--------------+
             |           |          |  |   |              |   |              |
             V           +----------+  +-->|  CacheFiles  |-->|  Ext3        |
        +---------+                        |  /var/cache  |   |  /dev/sda6   |
        |         |                        +--------------+   +--------------+
        |   VFS   |                                ^                     ^
        |         |                                |                     |
        +---------+                                +--------------+      |
             |                  KERNEL SPACE                      |      |
        ~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|~~~~~~|~~~~
             |                  USER SPACE                        |      |
             V                                                    |      |
        +---------+                                           +--------------+
        |         |                                           |              |
        | Process |                                           | cachefilesd  |
        |         |                                           |              |
        +---------+                                           +--------------+


FS-Cache does not follow the idea of completely loading every netfs file
opened in its entirety into a cache before permitting it to be accessed and
then serving the pages out of that cache rather than the netfs inode because:

 (1) It must be practical to operate without a cache.

 (2) The size of any accessible file must not be limited to the size of the
     cache.

 (3) The combined size of all opened files (this includes mapped libraries)
     must not be limited to the size of the cache.

 (4) The user should not be forced to download an entire file just to do a
     one-off access of a small portion of it (such as might be done with the
     "file" program).

It instead serves the cache out in chunks as and when requested by the netfs
using it.

FS-Cache가 제공하는 기능

여러 캐시를 동시에 사용할 수 있으며 tag로 캐시를 명시적으로 선택할 수 있습니다. 접근 중인 경우에도 캐시를 언제든 추가하거나 제거할 수 있습니다.

netfs interface는 netfs와 backend 어느 쪽이든 파일의 caching 기능을 철회할 수 있게 합니다. netfs에는 가능한 한 오류를 적게 반환하고, 캐시의 내부 실패를 netfs가 알지 못한 채 계속 동작하게 하는 방식을 선호합니다.

cookie는 cache, volume, data file의 세 종류입니다. cache cookie는 캐시 전체를 나타내며 보통 netfs에 보이지 않습니다. netfs는 파일 모음, 일반적으로 superblock에 해당하는 volume cookie를 받고 inode에 해당하는 데이터를 caching할 때 data file cookie를 사용합니다.

volume은 key로 매칭합니다. 이 key는 한 superblock을 다른 것과 구별하는 데 필요한 모든 정보를 encode한 출력 가능한 문자열이고 유효한 pathname이어야 합니다. cell name, server address, volume name, share path 등을 조합할 수 있습니다.

data cookie도 key로 매칭하지만 이 key는 volume 안의 객체를 나타내는 binary blob입니다. volume key를 blob에 다시 넣을 필요는 없습니다. inode number와 uniquifier 또는 file handle 등이 들어갈 수 있습니다.

cookie를 in-use로 표시하면 backing resource를 설정하고 pin하여 culling을 막습니다. 짧은 시간 사용되지 않은 cookie는 timed garbage collection으로 제거해 resource 부하를 줄입니다. 이 동작은 파일 open과 close에 맞춰 사용하도록 의도되었습니다.

하나의 cookie는 동시에 여러 번 in-use로 표시할 수 있으며 각 mark는 대응하는 unuse가 필요합니다.

begin/end access 함수는 operation 동안 cache withdrawal을 지연하고 구조체를 보고 있는 동안 해제되지 않게 합니다.

data I/O는 netfs가 `iov_iter`로 설명한 buffer와 cache 사이의 비동기 DIO로 수행합니다. invalidation 기능은 캐시 데이터를 버리고 오래된 데이터에 접근 중인 I/O를 처리합니다. cookie를 release할 때 retire하면 객체를 캐시에서 제거합니다.

netfs용 FS-Cache API는 `Documentation/filesystems/caching/netfs-api.rst`, cache backend API는 `Documentation/filesystems/caching/backend-api.rst`에 있습니다.

FS-Cache provides the following facilities:

   * More than one cache can be used at once.  Caches can be selected
     explicitly by use of tags.

   * Caches can be added / removed at any time, even whilst being accessed.

   * The netfs is provided with an interface that allows either party to
     withdraw caching facilities from a file (required for (2)).

   * The interface to the netfs returns as few errors as possible, preferring
     rather to let the netfs remain oblivious.

   * There are three types of cookie: cache, volume and data file cookies.
     Cache cookies represent the cache as a whole and are not normally visible
     to the netfs; the netfs gets a volume cookie to represent a collection of
     files (typically something that a netfs would get for a superblock); and
     data file cookies are used to cache data (something that would be got for
     an inode).

   * Volumes are matched using a key.  This is a printable string that is used
     to encode all the information that might be needed to distinguish one
     superblock, say, from another.  This would be a compound of things like
     cell name or server address, volume name or share path.  It must be a
     valid pathname.

   * Cookies are matched using a key.  This is a binary blob and is used to
     represent the object within a volume (so the volume key need not form
     part of the blob).  This might include things like an inode number and
     uniquifier or a file handle.

   * Cookie resources are set up and pinned by marking the cookie in-use.
     This prevents the backing resources from being culled.  Timed garbage
     collection is employed to eliminate cookies that haven't been used for a
     short while, thereby reducing resource overload.  This is intended to be
     used when a file is opened or closed.

     A cookie can be marked in-use multiple times simultaneously; each mark
     must be unused.

   * Begin/end access functions are provided to delay cache withdrawal for the
     duration of an operation and prevent structs from being freed whilst
     we're looking at them.

   * Data I/O is done by asynchronous DIO to/from a buffer described by the
     netfs using an iov_iter.

   * An invalidation facility is available to discard data from the cache and
     to deal with I/O that's in progress that is accessing old data.

   * Cookies can be "retired" upon release, thereby causing the object to be
     removed from the cache.


The netfs API to FS-Cache can be found in:

        Documentation/filesystems/caching/netfs-api.rst

The cache backend API to FS-Cache can be found in:

        Documentation/filesystems/caching/backend-api.rst

`/proc/fs/fscache/stats`

`CONFIG_FSCACHE_STATS=y`로 FS-Cache를 빌드하면 통계를 수집해 `/proc/fs/fscache/stats`에 표시합니다.

`Cookies` class에서 `n`은 할당된 data storage cookie 수, `v`는 volume index cookie 수, `vcol`은 volume index key 충돌 수, `voom`은 volume cookie 할당 중 OOM 사건 수입니다.

`Acquire`의 `n`은 acquire cookie 요청 수, `ok`는 성공 수, `oom`은 `ENOMEM`으로 실패한 수입니다.

`LRU`의 `n`은 현재 LRU에 있는 cookie 수, `exp`는 LRU에서 만료된 수, `rmv`는 LRU에서 제거된 수, `drp`는 LRU 상태에서 relinquish 또는 withdraw된 수, `at`은 다음 LRU cull까지의 jiffy입니다.

`Invals n`은 invalidation 횟수입니다. `Updates n`은 update cookie 요청 수, `rsz`는 resize 요청 수, `rsn`은 건너뛴 resize 요청 수입니다.

`Relinqs n`은 relinquish cookie 요청 수, `rtr`은 `retire=true`인 요청 수, `drop`은 재acquire를 더 이상 막지 않는 cookie 수입니다.

`NoSpace nwr`은 공간 부족으로 거부된 write 요청 수, `ncr`은 create 요청 수, `cull`은 공간을 만들기 위해 cull한 객체 수입니다. `IO rd`와 `wr`은 캐시 read 및 write operation 수입니다.

Netfslib도 자체 통계 counter를 추가합니다.

Statistical Information
=======================

If FS-Cache is compiled with the following options enabled::

        CONFIG_FSCACHE_STATS=y

then it will gather certain statistics and display them through:

        /proc/fs/fscache/stats

This shows counts of a number of events that can happen in FS-Cache:

+--------------+-------+-------------------------------------------------------+
|CLASS         |EVENT  |MEANING                                                |
+==============+=======+=======================================================+
|Cookies       |n=N    |Number of data storage cookies allocated               |
+              +-------+-------------------------------------------------------+
|              |v=N    |Number of volume index cookies allocated               |
+              +-------+-------------------------------------------------------+
|              |vcol=N |Number of volume index key collisions                  |
+              +-------+-------------------------------------------------------+
|              |voom=N |Number of OOM events when allocating volume cookies    |
+--------------+-------+-------------------------------------------------------+
|Acquire       |n=N    |Number of acquire cookie requests seen                 |
+              +-------+-------------------------------------------------------+
|              |ok=N   |Number of acq reqs succeeded                           |
+              +-------+-------------------------------------------------------+
|              |oom=N  |Number of acq reqs failed on ENOMEM                    |
+--------------+-------+-------------------------------------------------------+
|LRU           |n=N    |Number of cookies currently on the LRU                 |
+              +-------+-------------------------------------------------------+
|              |exp=N  |Number of cookies expired off of the LRU               |
+              +-------+-------------------------------------------------------+
|              |rmv=N  |Number of cookies removed from the LRU                 |
+              +-------+-------------------------------------------------------+
|              |drp=N  |Number of LRU'd cookies relinquished/withdrawn         |
+              +-------+-------------------------------------------------------+
|              |at=N   |Time till next LRU cull (jiffies)                      |
+--------------+-------+-------------------------------------------------------+
|Invals        |n=N    |Number of invalidations                                |
+--------------+-------+-------------------------------------------------------+
|Updates       |n=N    |Number of update cookie requests seen                  |
+              +-------+-------------------------------------------------------+
|              |rsz=N  |Number of resize requests                              |
+              +-------+-------------------------------------------------------+
|              |rsn=N  |Number of skipped resize requests                      |
+--------------+-------+-------------------------------------------------------+
|Relinqs       |n=N    |Number of relinquish cookie requests seen              |
+              +-------+-------------------------------------------------------+
|              |rtr=N  |Number of rlq reqs with retire=true                    |
+              +-------+-------------------------------------------------------+
|              |drop=N |Number of cookies no longer blocking re-acquisition    |
+--------------+-------+-------------------------------------------------------+
|NoSpace       |nwr=N  |Number of write requests refused due to lack of space  |
+              +-------+-------------------------------------------------------+
|              |ncr=N  |Number of create requests refused due to lack of space |
+              +-------+-------------------------------------------------------+
|              |cull=N |Number of objects culled to make space                 |
+--------------+-------+-------------------------------------------------------+
|IO            |rd=N   |Number of read operations in the cache                 |
+              +-------+-------------------------------------------------------+
|              |wr=N   |Number of write operations in the cache                |
+--------------+-------+-------------------------------------------------------+

Netfslib will also add some stats counters of its own.

Cache cookie 목록

FS-Cache는 cache cookie 목록을 procfs로 제공합니다. 원문 경로 표기에는 `/proc/fs/fscache/cookies`가 나오지만 예시 명령은 `/proc/fs/fscache/caches`를 읽습니다.

출력의 `CACHE`는 trace에도 표시되는 cache cookie debug ID, `REF`는 cookie reference 수, `VOLS`는 이 캐시의 volume cookie 수, `OBJS`는 사용 중인 cache object 수, `ACCES`는 캐시를 pin하는 access 수입니다.

`S`는 상태, `NAME`은 캐시 이름입니다. 상태는 inactive `-`, preparing `P`, active `A`, error `E`, withdrawing `W` 중 하나입니다.

Cache List
==========

FS-Cache provides a list of cache cookies:

        /proc/fs/fscache/cookies

This will look something like::

        # cat /proc/fs/fscache/caches
        CACHE    REF   VOLS  OBJS  ACCES S NAME
        ======== ===== ===== ===== ===== = ===============
        00000001     2     1  2123     1 A default

where the columns are:

        =======        ===============================================================
        COLUMN        DESCRIPTION
        =======        ===============================================================
        CACHE        Cache cookie debug ID (also appears in traces)
        REF        Number of references on the cache cookie
        VOLS        Number of volumes cookies in this cache
        OBJS        Number of cache objects in use
        ACCES        Number of accesses pinning the cache
        S        State
        NAME        Name of the cache.
        =======        ===============================================================

The state can be (-) Inactive, (P)reparing, (A)ctive, (E)rror or (W)ithdrawing.

Volume cookie 목록

FS-Cache는 `/proc/fs/fscache/volumes`에 volume cookie 목록을 제공합니다.

`VOLUME`은 trace에도 표시되는 volume cookie debug ID, `REF`는 volume cookie reference 수, `nCOOK`은 volume 안의 cookie 수, `ACC`는 캐시를 pin하는 access 수입니다.

`FL`은 volume cookie flag, `CACHE`는 캐시 이름 또는 `-`, `KEY`는 volume indexing key입니다.

Volume List
===========

FS-Cache provides a list of volume cookies:

        /proc/fs/fscache/volumes

This will look something like::

        VOLUME   REF   nCOOK ACC FL CACHE           KEY
        ======== ===== ===== === == =============== ================
        00000001    55    54   1 00 default         afs,example.com,100058

where the columns are:

        =======        ===============================================================
        COLUMN        DESCRIPTION
        =======        ===============================================================
        VOLUME        The volume cookie debug ID (also appears in traces)
        REF        Number of references on the volume cookie
        nCOOK        Number of cookies in the volume
        ACC        Number of accesses pinning the cache
        FL        Flags on the volume cookie
        CACHE        Name of the cache or "-"
        KEY        The indexing key for the volume
        =======        ===============================================================

Data cookie 목록

FS-Cache는 `/proc/fs/fscache/cookies`에 data cookie 목록을 제공합니다.

`COOKIE`는 trace에도 표시되는 cookie debug ID, `VOLUME`은 부모 volume cookie debug ID입니다. `REF`는 원문 설명상 volume cookie reference 수입니다.

`ACT`는 cookie가 in-use로 표시된 횟수, `ACC`는 cookie access pin 수, `S`는 cookie 상태, `FL`은 cookie flag, `DEF`는 key와 auxiliary data입니다.

Cookie List
===========

FS-Cache provides a list of cookies:

        /proc/fs/fscache/cookies

This will look something like::

        # head /proc/fs/fscache/cookies
        COOKIE   VOLUME   REF ACT ACC S FL DEF
        ======== ======== === === === = == ================
        00000435 00000001   1   0  -1 - 08 0000000201d080070000000000000000, 0000000000000000
        00000436 00000001   1   0  -1 - 00 0000005601d080080000000000000000, 0000000000000051
        00000437 00000001   1   0  -1 - 08 00023b3001d0823f0000000000000000, 0000000000000000
        00000438 00000001   1   0  -1 - 08 0000005801d0807b0000000000000000, 0000000000000000
        00000439 00000001   1   0  -1 - 08 00023b3201d080a10000000000000000, 0000000000000000
        0000043a 00000001   1   0  -1 - 08 00023b3401d080a30000000000000000, 0000000000000000
        0000043b 00000001   1   0  -1 - 08 00023b3601d080b30000000000000000, 0000000000000000
        0000043c 00000001   1   0  -1 - 08 00023b3801d080b40000000000000000, 0000000000000000

where the columns are:

        =======        ===============================================================
        COLUMN        DESCRIPTION
        =======        ===============================================================
        COOKIE        The cookie debug ID (also appears in traces)
        VOLUME        The parent volume cookie debug ID
        REF        Number of references on the volume cookie
        ACT        Number of times the cookie is marked for in use
        ACC        Number of access pins in the cookie
        S        State of the cookie
        FL        Flags on the cookie
        DEF        Key, auxiliary data
        =======        ===============================================================

NETFS runtime debugging

`CONFIG_NETFS_DEBUG`를 활성화하면 `/sys/module/netfs/parameters/debug` 값을 조정해 FS-Cache와 NETFS runtime debugging을 켤 수 있습니다.

bitmask의 bit 0~2, 값 1·2·4는 cache management의 function entry, function exit, general stream입니다. bit 3~5, 값 8·16·32는 cookie management의 같은 세 stream입니다. bit 6~8은 사용하지 않습니다. bit 9~11, 값 512·1024·2048은 I/O operation management의 entry, exit, general stream입니다.

필요한 값을 OR로 결합해 control file에 씁니다. `echo $((1|8|512)) > /sys/module/netfs/parameters/debug`는 세 영역의 function entry debugging을 모두 켭니다.

Debugging
=========

If CONFIG_NETFS_DEBUG is enabled, the FS-Cache facility and NETFS support can
have runtime debugging enabled by adjusting the value in::

        /sys/module/netfs/parameters/debug

This is a bitmask of debugging streams to enable:

        =======        =======        ===============================        =======================
        BIT        VALUE        STREAM                                POINT
        =======        =======        ===============================        =======================
        0        1        Cache management                Function entry trace
        1        2                                        Function exit trace
        2        4                                        General
        3        8        Cookie management                Function entry trace
        4        16                                        Function exit trace
        5        32                                        General
        6-8                                                (Not used)
        9        512        I/O operation management        Function entry trace
        10        1024                                        Function exit trace
        11        2048                                        General
        =======        =======        ===============================        =======================

The appropriate set of values should be OR'd together and the result written to
the control file.  For example::

        echo $((1|8|512)) >/sys/module/netfs/parameters/debug

will turn on all function entry debugging.