Document cleancache, its APIs and sysfs interface. Signed-off-by: Suren Baghdasaryan --- .../admin-guide/mm/cleancache_sysfs.rst | 51 ++++++++++++++ Documentation/admin-guide/mm/index.rst | 1 + Documentation/mm/cleancache.rst | 68 +++++++++++++++++++ Documentation/mm/index.rst | 1 + MAINTAINERS | 2 + 5 files changed, 123 insertions(+) create mode 100644 Documentation/admin-guide/mm/cleancache_sysfs.rst create mode 100644 Documentation/mm/cleancache.rst diff --git a/Documentation/admin-guide/mm/cleancache_sysfs.rst b/Documentation/admin-guide/mm/cleancache_sysfs.rst new file mode 100644 index 000000000000..503f17008046 --- /dev/null +++ b/Documentation/admin-guide/mm/cleancache_sysfs.rst @@ -0,0 +1,51 @@ +========================== +Cleancache Sysfs Interface +========================== + +If CONFIG_CLEANCACHE_SYSFS is enabled, monitoring of cleancache performance +can be done via sysfs in the ``/sys/kernel/mm/cleancache`` directory. +The effectiveness of cleancache can be measured (across all filesystems) +with provided stats. +Global stats are published directly under ``/sys/kernel/mm/cleancache`` and +include: + +``stored`` + number of successful cleancache folio stores. + +``skipped`` + number of folios skipped during cleancache store operation. + +``restored`` + number of successful cleancache folio restore operations. + +``missed`` + number of failed cleancache folio restore operations. + +``reclaimed`` + number of folios reclaimed from the cleancache due to insufficient + memory. + +``recalled`` + number of times cleancache folio content was discarded as a result + of the cleancache backend taking the folio back. + +``invalidated`` + number of times cleancache folio content was discarded as a result + of invalidation. + +``cached`` + number of folios currently cached in the cleancache. + +Per-pool stats are published under ``/sys/kernel/mm/cleancache/`` +where "pool name" is the name pool was registered under. These stats +include: + +``size`` + number of folios donated to this pool. + +``cached`` + number of folios currently cached in the pool. + +``recalled`` + number of times cleancache folio content was discarded as a result + of the cleancache backend taking the folio back from the pool. diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index ebc83ca20fdc..e22336e5c9d2 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -25,6 +25,7 @@ the Linux memory management. :maxdepth: 1 concepts + cleancache_sysfs cma_debugfs damon/index hugetlbpage diff --git a/Documentation/mm/cleancache.rst b/Documentation/mm/cleancache.rst new file mode 100644 index 000000000000..bd4ee7df2125 --- /dev/null +++ b/Documentation/mm/cleancache.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +Cleancache +========== + +Motivation +========== + +Cleancache is a feature to utilize unused reserved memory for extending +page cache. + +Cleancache can be thought of as a folio-granularity victim cache for clean +file-backed pages that the kernel's pageframe replacement algorithm would +like to keep around, but can't since there isn't enough memory. When the +memory reclaim mechanism "evicts" a folio, it stores the data contained +in the folio into cleancache memory which is not directly accessible or +addressable by the kernel and is of unknown and possibly time-varying +size. + +Later, when a filesystem wishes to access a folio in a file on disk, it +first checks cleancache to see if it already contains required data; if +it does, the folio data is copied into the kernel and a disk access is +avoided. + +The memory cleancache uses is donated by other system components, which +reserve memory not directly addressable by the kernel. By donating this +memory to cleancache, the memory owner enables its utilization while it +is not used. Memory donation is done using cleancache backend API and any +donated memory can be taken back at any time by its donor with no delay +and with guaranteed success. Since cleancache uses this memory only to +store clean file-backed data, it can be dropped at any time and therefore +the donor's request to take back the memory can always be satisfied. + +Implementation Overview +======================= + +Cleancache "backend" registers itself with cleancache "frontend" and gets +a unique pool_id, which it can use in all later API calls to identify the +pool of folios it donates. +Once registered, backend can call cleancache_backend_put_folio() or +cleancache_backend_put_folios() to donate memory to cleancache. Note that +cleancache currently supports only 0-order folios and will not accept +larger-order ones. Once the backend needs that memory back, it can get it +by calling cleancache_backend_get_folio(). Only the original backend can +take the folio it donated from the cleancache. + +Kernel uses cleancache by first calling cleancache_add_fs() to register +each file system and then using a combination of cleancache_store_folio(), +cleancache_restore_folio(), cleancache_invalidate_{folio|inode} to store, +restore and invalidate folio content. +cleancache_{start|end}_inode_walk() are used to walk over folios inside +an inode and cleancache_restore_from_inode() is used to restore folios +during such walks. + +From kernel's point of view folios which are copied into cleancache have +an indefinite lifetime which is completely unknowable by the kernel and so +may or may not still be in cleancache at any later time. Thus, as its name +implies, cleancache is not suitable for dirty folios. Cleancache has +complete discretion over what folios to preserve and what folios to discard +and when. + +Cleancache Performance Metrics +============================== + +Cleancache performance can be measured and monitored using metrics provided +via sysfs interface under ``/sys/kernel/mm/cleancache`` directory. The +interface is described in Documentation/admin-guide/mm/cleancache_sysfs.rst. diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst index ba6a8872849b..7997879e0695 100644 --- a/Documentation/mm/index.rst +++ b/Documentation/mm/index.rst @@ -41,6 +41,7 @@ documentation, or deleted if it has served its purpose. allocation-profiling arch_pgtable_helpers balance + cleancache damon/index free_page_reporting hmm diff --git a/MAINTAINERS b/MAINTAINERS index eb35973e10c8..3aabed281b71 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6058,6 +6058,8 @@ M: Suren Baghdasaryan M: Minchan Kim L: linux-mm@kvack.org S: Maintained +F: Documentation/admin-guide/mm/cleancache_sysfs.rst +F: Documentation/mm/cleancache.rst F: include/linux/cleancache.h F: mm/cleancache.c F: mm/cleancache_sysfs.c -- 2.51.1.851.g4ebd6896fd-goog