cleancache.rst 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  1. .. _cleancache:
  2. ==========
  3. Cleancache
  4. ==========
  5. Motivation
  6. ==========
  7. Cleancache is a new optional feature provided by the VFS layer that
  8. potentially dramatically increases page cache effectiveness for
  9. many workloads in many environments at a negligible cost.
  10. Cleancache can be thought of as a page-granularity victim cache for clean
  11. pages that the kernel's pageframe replacement algorithm (PFRA) would like
  12. to keep around, but can't since there isn't enough memory. So when the
  13. PFRA "evicts" a page, it first attempts to use cleancache code to
  14. put the data contained in that page into "transcendent memory", memory
  15. that is not directly accessible or addressable by the kernel and is
  16. of unknown and possibly time-varying size.
  17. Later, when a cleancache-enabled filesystem wishes to access a page
  18. in a file on disk, it first checks cleancache to see if it already
  19. contains it; if it does, the page of data is copied into the kernel
  20. and a disk access is avoided.
  21. Transcendent memory "drivers" for cleancache are currently implemented
  22. in Xen (using hypervisor memory) and zcache (using in-kernel compressed
  23. memory) and other implementations are in development.
  24. :ref:`FAQs <faq>` are included below.
  25. Implementation Overview
  26. =======================
  27. A cleancache "backend" that provides transcendent memory registers itself
  28. to the kernel's cleancache "frontend" by calling cleancache_register_ops,
  29. passing a pointer to a cleancache_ops structure with funcs set appropriately.
  30. The functions provided must conform to certain semantics as follows:
  31. Most important, cleancache is "ephemeral". Pages which are copied into
  32. cleancache have an indefinite lifetime which is completely unknowable
  33. by the kernel and so may or may not still be in cleancache at any later time.
  34. Thus, as its name implies, cleancache is not suitable for dirty pages.
  35. Cleancache has complete discretion over what pages to preserve and what
  36. pages to discard and when.
  37. Mounting a cleancache-enabled filesystem should call "init_fs" to obtain a
  38. pool id which, if positive, must be saved in the filesystem's superblock;
  39. a negative return value indicates failure. A "put_page" will copy a
  40. (presumably about-to-be-evicted) page into cleancache and associate it with
  41. the pool id, a file key, and a page index into the file. (The combination
  42. of a pool id, a file key, and an index is sometimes called a "handle".)
  43. A "get_page" will copy the page, if found, from cleancache into kernel memory.
  44. An "invalidate_page" will ensure the page no longer is present in cleancache;
  45. an "invalidate_inode" will invalidate all pages associated with the specified
  46. file; and, when a filesystem is unmounted, an "invalidate_fs" will invalidate
  47. all pages in all files specified by the given pool id and also surrender
  48. the pool id.
  49. An "init_shared_fs", like init_fs, obtains a pool id but tells cleancache
  50. to treat the pool as shared using a 128-bit UUID as a key. On systems
  51. that may run multiple kernels (such as hard partitioned or virtualized
  52. systems) that may share a clustered filesystem, and where cleancache
  53. may be shared among those kernels, calls to init_shared_fs that specify the
  54. same UUID will receive the same pool id, thus allowing the pages to
  55. be shared. Note that any security requirements must be imposed outside
  56. of the kernel (e.g. by "tools" that control cleancache). Or a
  57. cleancache implementation can simply disable shared_init by always
  58. returning a negative value.
  59. If a get_page is successful on a non-shared pool, the page is invalidated
  60. (thus making cleancache an "exclusive" cache). On a shared pool, the page
  61. is NOT invalidated on a successful get_page so that it remains accessible to
  62. other sharers. The kernel is responsible for ensuring coherency between
  63. cleancache (shared or not), the page cache, and the filesystem, using
  64. cleancache invalidate operations as required.
  65. Note that cleancache must enforce put-put-get coherency and get-get
  66. coherency. For the former, if two puts are made to the same handle but
  67. with different data, say AAA by the first put and BBB by the second, a
  68. subsequent get can never return the stale data (AAA). For get-get coherency,
  69. if a get for a given handle fails, subsequent gets for that handle will
  70. never succeed unless preceded by a successful put with that handle.
  71. Last, cleancache provides no SMP serialization guarantees; if two
  72. different Linux threads are simultaneously putting and invalidating a page
  73. with the same handle, the results are indeterminate. Callers must
  74. lock the page to ensure serial behavior.
  75. Cleancache Performance Metrics
  76. ==============================
  77. If properly configured, monitoring of cleancache is done via debugfs in
  78. the `/sys/kernel/debug/cleancache` directory. The effectiveness of cleancache
  79. can be measured (across all filesystems) with:
  80. ``succ_gets``
  81. number of gets that were successful
  82. ``failed_gets``
  83. number of gets that failed
  84. ``puts``
  85. number of puts attempted (all "succeed")
  86. ``invalidates``
  87. number of invalidates attempted
  88. A backend implementation may provide additional metrics.
  89. .. _faq:
  90. FAQ
  91. ===
  92. * Where's the value? (Andrew Morton)
  93. Cleancache provides a significant performance benefit to many workloads
  94. in many environments with negligible overhead by improving the
  95. effectiveness of the pagecache. Clean pagecache pages are
  96. saved in transcendent memory (RAM that is otherwise not directly
  97. addressable to the kernel); fetching those pages later avoids "refaults"
  98. and thus disk reads.
  99. Cleancache (and its sister code "frontswap") provide interfaces for
  100. this transcendent memory (aka "tmem"), which conceptually lies between
  101. fast kernel-directly-addressable RAM and slower DMA/asynchronous devices.
  102. Disallowing direct kernel or userland reads/writes to tmem
  103. is ideal when data is transformed to a different form and size (such
  104. as with compression) or secretly moved (as might be useful for write-
  105. balancing for some RAM-like devices). Evicted page-cache pages (and
  106. swap pages) are a great use for this kind of slower-than-RAM-but-much-
  107. faster-than-disk transcendent memory, and the cleancache (and frontswap)
  108. "page-object-oriented" specification provides a nice way to read and
  109. write -- and indirectly "name" -- the pages.
  110. In the virtual case, the whole point of virtualization is to statistically
  111. multiplex physical resources across the varying demands of multiple
  112. virtual machines. This is really hard to do with RAM and efforts to
  113. do it well with no kernel change have essentially failed (except in some
  114. well-publicized special-case workloads). Cleancache -- and frontswap --
  115. with a fairly small impact on the kernel, provide a huge amount
  116. of flexibility for more dynamic, flexible RAM multiplexing.
  117. Specifically, the Xen Transcendent Memory backend allows otherwise
  118. "fallow" hypervisor-owned RAM to not only be "time-shared" between multiple
  119. virtual machines, but the pages can be compressed and deduplicated to
  120. optimize RAM utilization. And when guest OS's are induced to surrender
  121. underutilized RAM (e.g. with "self-ballooning"), page cache pages
  122. are the first to go, and cleancache allows those pages to be
  123. saved and reclaimed if overall host system memory conditions allow.
  124. And the identical interface used for cleancache can be used in
  125. physical systems as well. The zcache driver acts as a memory-hungry
  126. device that stores pages of data in a compressed state. And
  127. the proposed "RAMster" driver shares RAM across multiple physical
  128. systems.
  129. * Why does cleancache have its sticky fingers so deep inside the
  130. filesystems and VFS? (Andrew Morton and Christoph Hellwig)
  131. The core hooks for cleancache in VFS are in most cases a single line
  132. and the minimum set are placed precisely where needed to maintain
  133. coherency (via cleancache_invalidate operations) between cleancache,
  134. the page cache, and disk. All hooks compile into nothingness if
  135. cleancache is config'ed off and turn into a function-pointer-
  136. compare-to-NULL if config'ed on but no backend claims the ops
  137. functions, or to a compare-struct-element-to-negative if a
  138. backend claims the ops functions but a filesystem doesn't enable
  139. cleancache.
  140. Some filesystems are built entirely on top of VFS and the hooks
  141. in VFS are sufficient, so don't require an "init_fs" hook; the
  142. initial implementation of cleancache didn't provide this hook.
  143. But for some filesystems (such as btrfs), the VFS hooks are
  144. incomplete and one or more hooks in fs-specific code are required.
  145. And for some other filesystems, such as tmpfs, cleancache may
  146. be counterproductive. So it seemed prudent to require a filesystem
  147. to "opt in" to use cleancache, which requires adding a hook in
  148. each filesystem. Not all filesystems are supported by cleancache
  149. only because they haven't been tested. The existing set should
  150. be sufficient to validate the concept, the opt-in approach means
  151. that untested filesystems are not affected, and the hooks in the
  152. existing filesystems should make it very easy to add more
  153. filesystems in the future.
  154. The total impact of the hooks to existing fs and mm files is only
  155. about 40 lines added (not counting comments and blank lines).
  156. * Why not make cleancache asynchronous and batched so it can more
  157. easily interface with real devices with DMA instead of copying each
  158. individual page? (Minchan Kim)
  159. The one-page-at-a-time copy semantics simplifies the implementation
  160. on both the frontend and backend and also allows the backend to
  161. do fancy things on-the-fly like page compression and
  162. page deduplication. And since the data is "gone" (copied into/out
  163. of the pageframe) before the cleancache get/put call returns,
  164. a great deal of race conditions and potential coherency issues
  165. are avoided. While the interface seems odd for a "real device"
  166. or for real kernel-addressable RAM, it makes perfect sense for
  167. transcendent memory.
  168. * Why is non-shared cleancache "exclusive"? And where is the
  169. page "invalidated" after a "get"? (Minchan Kim)
  170. The main reason is to free up space in transcendent memory and
  171. to avoid unnecessary cleancache_invalidate calls. If you want inclusive,
  172. the page can be "put" immediately following the "get". If
  173. put-after-get for inclusive becomes common, the interface could
  174. be easily extended to add a "get_no_invalidate" call.
  175. The invalidate is done by the cleancache backend implementation.
  176. * What's the performance impact?
  177. Performance analysis has been presented at OLS'09 and LCA'10.
  178. Briefly, performance gains can be significant on most workloads,
  179. especially when memory pressure is high (e.g. when RAM is
  180. overcommitted in a virtual workload); and because the hooks are
  181. invoked primarily in place of or in addition to a disk read/write,
  182. overhead is negligible even in worst case workloads. Basically
  183. cleancache replaces I/O with memory-copy-CPU-overhead; on older
  184. single-core systems with slow memory-copy speeds, cleancache
  185. has little value, but in newer multicore machines, especially
  186. consolidated/virtualized machines, it has great value.
  187. * How do I add cleancache support for filesystem X? (Boaz Harrash)
  188. Filesystems that are well-behaved and conform to certain
  189. restrictions can utilize cleancache simply by making a call to
  190. cleancache_init_fs at mount time. Unusual, misbehaving, or
  191. poorly layered filesystems must either add additional hooks
  192. and/or undergo extensive additional testing... or should just
  193. not enable the optional cleancache.
  194. Some points for a filesystem to consider:
  195. - The FS should be block-device-based (e.g. a ram-based FS such
  196. as tmpfs should not enable cleancache)
  197. - To ensure coherency/correctness, the FS must ensure that all
  198. file removal or truncation operations either go through VFS or
  199. add hooks to do the equivalent cleancache "invalidate" operations
  200. - To ensure coherency/correctness, either inode numbers must
  201. be unique across the lifetime of the on-disk file OR the
  202. FS must provide an "encode_fh" function.
  203. - The FS must call the VFS superblock alloc and deactivate routines
  204. or add hooks to do the equivalent cleancache calls done there.
  205. - To maximize performance, all pages fetched from the FS should
  206. go through the do_mpag_readpage routine or the FS should add
  207. hooks to do the equivalent (cf. btrfs)
  208. - Currently, the FS blocksize must be the same as PAGESIZE. This
  209. is not an architectural restriction, but no backends currently
  210. support anything different.
  211. - A clustered FS should invoke the "shared_init_fs" cleancache
  212. hook to get best performance for some backends.
  213. * Why not use the KVA of the inode as the key? (Christoph Hellwig)
  214. If cleancache would use the inode virtual address instead of
  215. inode/filehandle, the pool id could be eliminated. But, this
  216. won't work because cleancache retains pagecache data pages
  217. persistently even when the inode has been pruned from the
  218. inode unused list, and only invalidates the data page if the file
  219. gets removed/truncated. So if cleancache used the inode kva,
  220. there would be potential coherency issues if/when the inode
  221. kva is reused for a different file. Alternately, if cleancache
  222. invalidated the pages when the inode kva was freed, much of the value
  223. of cleancache would be lost because the cache of pages in cleanache
  224. is potentially much larger than the kernel pagecache and is most
  225. useful if the pages survive inode cache removal.
  226. * Why is a global variable required?
  227. The cleancache_enabled flag is checked in all of the frequently-used
  228. cleancache hooks. The alternative is a function call to check a static
  229. variable. Since cleancache is enabled dynamically at runtime, systems
  230. that don't enable cleancache would suffer thousands (possibly
  231. tens-of-thousands) of unnecessary function calls per second. So the
  232. global variable allows cleancache to be enabled by default at compile
  233. time, but have insignificant performance impact when cleancache remains
  234. disabled at runtime.
  235. * Does cleanache work with KVM?
  236. The memory model of KVM is sufficiently different that a cleancache
  237. backend may have less value for KVM. This remains to be tested,
  238. especially in an overcommitted system.
  239. * Does cleancache work in userspace? It sounds useful for
  240. memory hungry caches like web browsers. (Jamie Lokier)
  241. No plans yet, though we agree it sounds useful, at least for
  242. apps that bypass the page cache (e.g. O_DIRECT).
  243. Last updated: Dan Magenheimer, April 13 2011