Skip to contentSkip to conversation

cachestat: a new syscall for page cache state of files

PATCH In review Nhat Pham 6 participants 15 messages May 3, 2023 – May 11, 2023

Subsystems (11)
lore
Share & tools
lore

Nhat Pham

author maintainer
#0 lore raw

v13 cover cachestat: a new syscall for page cache state of files

Changelog:
v13:
* Change the API, putting the offset and length arguments into a struct, passing only a userspace address to the syscall. It allows for explicit 64 bit length. (suggested by Jens Axboe) (patch 2)
v12:
* Update the cover letter with more cachestat usecase and security concerns (suggested by Johannes Weiner and Andres Freund).
* Fix a bug that crashes cachestat when processing recently evicted pages.
* Add a new benchmark for cachestat v.s mincore
v11:
* Clean up code and comments/documentation.
(patch 1 and 2) (suggested by Matthew Wilcox)
* Drop support for hugetlbfs (patch 2)
(from discussion with Johannes Weiner and Matthew Wilcox).
v10:
* Reorder the arguments for archs with alignment requirements. (patch 2) (suggested by Arnd Bergmann)
v9:
* Remove syscall from all the architectures syscall table except x86

    (patch 2)

* API change: handle different cases for offset and add compat syscall. (patch 2) (suggested by Johannes Weiner and Arnd Bergmann)
v8:
* Add syscall to mips syscall tables (detected by kernel test robot)

    (patch 2)
  * Add a missing return (suggested by Yu Zhao) (patch 2)
v7:
  * Fix and use lru_gen_test_recent (suggested by Brian Foster)
    (patch 2)

* Small formatting and organizational fixes
v6:
* Add a missing fdput() (suggested by Brian Foster) (patch 2)
* Replace cstat_size with cstat_version (suggested by Brian Foster)

    (patch 2)
  * Add conditional resched to the xas walk. (suggested by Hillf Danton)
    (patch 2)

v5:
* Separate first patch into its own series. (suggested by Andrew Morton)
* Expose filemap_cachestat() to non-syscall usage (patch 2) (suggested by Brian Foster).
* Fix some build errors from last version.

    (patch 2)

* Explain eviction and recent eviction in the draft man page and documentation (suggested by Andrew Morton).
(patch 2)
v4:
* Refactor cachestat and move it to mm/filemap.c (patch 3) (suggested by Brian Foster)
* Remove redundant checks (!folio, access_ok)
(patch 3) (suggested by Matthew Wilcox and Al Viro)
* Fix a bug in handling multipages folio.
(patch 3) (suggested by Matthew Wilcox)
* Add a selftest for shmem files, which can be used to test huge pages (patch 4) (suggested by Johannes Weiner)
v3:
* Fix some minor formatting issues and build errors.
* Add the new syscall entry to missing architecture syscall tables.

    (patch 3).

* Add flags argument for the syscall. (patch 3).
* Clean up the recency refactoring (patch 2) (suggested by Yu Zhao)
* Add the new Kconfig (CONFIG_CACHESTAT) to disable the syscall. (patch 3) (suggested by Josh Triplett)
v2:
* len == 0 means query to EOF. len < 0 is invalid.
(patch 3) (suggested by Brian Foster)
* Make cachestat extensible by adding the cstat_size argument in the syscall (patch 3)

There is currently no good way to query the page cache statistics of large files and directory trees. There is mincore(), but it scales poorly: the kernel writes out a lot of bitmap data that userspace has to aggregate, when the user really does not care about per-page information in that case. The user also needs to mmap and unmap each file as it goes along, which can be quite slow as well.

Some use cases where this information could come in handy:
* Allowing database to decide whether to perform an index scan or direct table queries based on the in-memory cache state of the index.
* Visibility into the writeback algorithm, for performance issues diagnostic.
* Workload-aware writeback pacing: estimating IO fulfilled by page cache (and IO to be done) within a range of a file, allowing for more frequent syncing when and where there is IO capacity, and batching when there is not.
* Computing memory usage of large files/directory trees, analogous to the du tool for disk usage.

More information about these use cases could be found in this thread:
https://lore.kernel.org/lkml/[email protected]/

This series of patches introduces a new system call, cachestat, that summarizes the page cache statistics (number of cached pages, dirty pages, pages marked for writeback, evicted pages etc.) of a file, in a specified range of bytes. It also include a selftest suite that tests some typical usage. Currently, the syscall is only wired in for x86 architecture.

This interface is inspired by past discussion and concerns with fincore, which has a similar design (and as a result, issues) as mincore. Relevant links:

https://lkml.indiana.edu/hypermail/linux/kernel/1302.1/04207.html
https://lkml.indiana.edu/hypermail/linux/kernel/1302.1/04209.html

I have also developed a small tool that computes the memory usage of files and directories, analogous to the du utility. User can choose between mincore or cachestat (with cachestat exporting more information than mincore). To compare the performance of these two options, I benchmarked the tool on the root directory of a Meta's server machine, each for five runs:

Using cachestat
real -- Median: 33.377s, Average: 33.475s, Standard Deviation: 0.3602 user -- Median: 4.08s, Average: 4.1078s, Standard Deviation: 0.0742 sys -- Median: 28.823s, Average: 28.8866s, Standard Deviation: 0.2689

Using mincore:
real -- Median: 102.352s, Average: 102.3442s, Standard Deviation: 0.2059 user -- Median: 10.149s, Average: 10.1482s, Standard Deviation: 0.0162 sys -- Median: 91.186s, Average: 91.2084s, Standard Deviation: 0.2046

I also ran both syscalls on a 2TB sparse file:

Using cachestat:

real    0m0.009s
user    0m0.000s
sys     0m0.009s

Using mincore:

real    0m37.510s
user    0m2.934s
sys     0m34.558s

Very large files like this are the pathological case for mincore. In fact, to compute the stats for a single 2TB file, mincore takes as long as cachestat takes to compute the stats for the entire tree! This could easily happen inadvertently when we run it on subdirectories. Mincore is clearly not suitable for a general-purpose command line tool.

Regarding security concerns, cachestat() should not pose any additional issues. The caller already has read permission to the file itself (since they need an fd to that file to call cachestat). This means that the caller can access the underlying data in its entirety, which is a much greater source of information (and as a result, a much greater security risk) than the cache status itself.

The latest API change (in v13 of the patch series) is suggested by Jens Axboe. It allows for 64-bit length argument, even on 32-bit architecture (which is previously not possible due to the limit on the number of syscall arguments). Furthermore, it eliminates the need for compatibility handling - every user can use the same ABI.

This series consist of 3 patches:

Nhat Pham (3):
workingset: refactor LRU refault to expose refault recency check
cachestat: implement cachestat syscall
selftests: Add selftests for cachestat

 MAINTAINERS                                   |   7 +
 arch/x86/entry/syscalls/syscall_32.tbl        |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl        |   1 +
 include/linux/swap.h                          |   1 +
 include/linux/syscalls.h                      |   5 +
 include/uapi/asm-generic/unistd.h             |   5 +-
 include/uapi/linux/mman.h                     |  14 +
 init/Kconfig                                  |  10 +
 kernel/sys_ni.c                               |   1 +
 mm/filemap.c                                  | 172 ++++++++++++
 mm/workingset.c                               | 150 ++++++----
 tools/testing/selftests/Makefile              |   1 +
 tools/testing/selftests/cachestat/.gitignore  |   2 +
 tools/testing/selftests/cachestat/Makefile    |   8 +
 .../selftests/cachestat/test_cachestat.c      | 258 ++++++++++++++++++
 15 files changed, 587 insertions(+), 49 deletions(-)
 create mode 100644 tools/testing/selftests/cachestat/.gitignore
 create mode 100644 tools/testing/selftests/cachestat/Makefile
 create mode 100644 tools/testing/selftests/cachestat/test_cachestat.c
Signature · 1 line
2.34.1
author maintainer
#1 lore raw

PATCH v13 1/3 workingset: refactor LRU refault to expose refault recency check

In preparation for computing recently evicted pages in cachestat, refactor workingset_refault and lru_gen_refault to expose a helper function that would test if an evicted page is recently evicted.

---
 include/linux/swap.h |   1 +
 mm/workingset.c      | 150 +++++++++++++++++++++++++++++--------------
 2 files changed, 103 insertions(+), 48 deletions(-)
include/linux/swap.h +1 -0
index 3c69cb653cb9..b2128df5edea 100644
@@ -368,6 +368,7 @@ static inline void folio_set_swap_entry(struct folio *folio, swp_entry_t entry)
 }
 
 /* linux/mm/workingset.c */
+bool workingset_test_recent(void *shadow, bool file, bool *workingset);
 void workingset_age_nonresident(struct lruvec *lruvec, unsigned long nr_pages);
 void *workingset_eviction(struct folio *folio, struct mem_cgroup *target_memcg);
 void workingset_refault(struct folio *folio, void *shadow);
mm/workingset.c +102 -48

213 lines not on this page · raw message

Signature · 1 line
2.34.1
maintainer Acked-by on v13 1/3
#2 lore raw

Re: [PATCH v13 1/3] workingset: refactor LRU refault to expose refault recency check

Quoted 5 lines · Nhat Pham

In preparation for computing recently evicted pages in cachestat, refactor workingset_refault and lru_gen_refault to expose a helper function that would test if an evicted page is recently evicted.

author maintainer
#3 lore raw

PATCH v13 2/3 cachestat: implement cachestat syscall

In reply to Nhat Pham

There is currently no good way to query the page cache state of large file sets and directory trees. There is mincore(), but it scales poorly:
the kernel writes out a lot of bitmap data that userspace has to aggregate, when the user really doesn not care about per-page information in that case. The user also needs to mmap and unmap each file as it goes along, which can be quite slow as well.

Some use cases where this information could come in handy:
* Allowing database to decide whether to perform an index scan or direct table queries based on the in-memory cache state of the index.
* Visibility into the writeback algorithm, for performance issues diagnostic.
* Workload-aware writeback pacing: estimating IO fulfilled by page cache (and IO to be done) within a range of a file, allowing for more frequent syncing when and where there is IO capacity, and batching when there is not.
* Computing memory usage of large files/directory trees, analogous to the du tool for disk usage.

More information about these use cases could be found in the following thread:

https://lore.kernel.org/lkml/[email protected]/

This patch implements a new syscall that queries cache state of a file and summarizes the number of cached pages, number of dirty pages, number of pages marked for writeback, number of (recently) evicted pages, etc. in a given range. Currently, the syscall is only wired in for x86 architecture.

NAME
cachestat - query the page cache statistics of a file.

SYNOPSIS

    #include <sys/mman.h>

    struct cachestat_range {
        __u64 off;
        __u64 len;
    };

    struct cachestat {
        __u64 nr_cache;
        __u64 nr_dirty;
        __u64 nr_writeback;
        __u64 nr_evicted;
        __u64 nr_recently_evicted;
    };

    int cachestat(unsigned int fd, struct cachestat_range *cstat_range,
        struct cachestat *cstat, unsigned int flags);

DESCRIPTION
cachestat() queries the number of cached pages, number of dirty pages, number of pages marked for writeback, number of evicted pages, number of recently evicted pages, in the bytes range given by off and len.

An evicted page is a page that is previously in the page cache but has been evicted since. A page is recently evicted if its last eviction was recent enough that its reentry to the cache would indicate that it is actively being used by the system, and that there is memory pressure on the system.

These values are returned in a cachestat struct, whose address is given by the cstat argument.

The off and len arguments must be non-negative integers. If len > 0, the queried range is [off, off + len]. If len == 0, we will query in the range from off to the end of the file.

The flags argument is unused for now, but is included for future extensibility. User should pass 0 (i.e no flag specified).

Currently, hugetlbfs is not supported.

Because the status of a page can change after cachestat() checks it but before it returns to the application, the returned values may contain stale information.

RETURN VALUE
On success, cachestat returns 0. On error, -1 is returned, and errno is set to indicate the error.

ERRORS
EFAULT cstat or cstat_args points to an invalid address.

EINVAL invalid flags.

EBADF invalid file descriptor.

EOPNOTSUPP file descriptor is of a hugetlbfs file

---
 arch/x86/entry/syscalls/syscall_32.tbl |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl |   1 +
 include/linux/syscalls.h               |   5 +
 include/uapi/asm-generic/unistd.h      |   5 +-
 include/uapi/linux/mman.h              |  14 ++
 init/Kconfig                           |  10 ++
 kernel/sys_ni.c                        |   1 +
 mm/filemap.c                           | 172 +++++++++++++++++++++++++
 8 files changed, 208 insertions(+), 1 deletion(-)
arch/x86/entry/syscalls/syscall_32.tbl +1 -0
index 320480a8db4f..bc0a3c941b35 100644
@@ -455,3 +455,4 @@
 448	i386	process_mrelease	sys_process_mrelease
 449	i386	futex_waitv		sys_futex_waitv
 450	i386	set_mempolicy_home_node		sys_set_mempolicy_home_node
+451	i386	cachestat		sys_cachestat
arch/x86/entry/syscalls/syscall_64.tbl +1 -0
index c84d12608cd2..227538b0ce80 100644
@@ -372,6 +372,7 @@
 448	common	process_mrelease	sys_process_mrelease
 449	common	futex_waitv		sys_futex_waitv
 450	common	set_mempolicy_home_node	sys_set_mempolicy_home_node
+451	common	cachestat		sys_cachestat
 
 #
 # Due to a historical design error, certain syscalls are numbered differently
include/linux/syscalls.h +5 -0
index 33a0ee3bcb2e..6648c07c4381 100644
@@ -72,6 +72,8 @@ struct open_how;
 struct mount_attr;
 struct landlock_ruleset_attr;
 enum landlock_rule_type;
+struct cachestat_range;
+struct cachestat;
 
 #include <linux/types.h>
 #include <linux/aio_abi.h>
@@ -1058,6 +1060,9 @@ asmlinkage long sys_memfd_secret(unsigned int flags);
 asmlinkage long sys_set_mempolicy_home_node(unsigned long start, unsigned long len,
 					    unsigned long home_node,
 					    unsigned long flags);
+asmlinkage long sys_cachestat(unsigned int fd,
+		struct cachestat_range __user *cstat_range,
+		struct cachestat __user *cstat, unsigned int flags);
 
 /*
  * Architecture-specific system calls
include/uapi/asm-generic/unistd.h +4 -1
index 45fa180cc56a..cd639fae9086 100644
@@ -886,8 +886,11 @@ __SYSCALL(__NR_futex_waitv, sys_futex_waitv)
 #define __NR_set_mempolicy_home_node 450
 __SYSCALL(__NR_set_mempolicy_home_node, sys_set_mempolicy_home_node)
 
+#define __NR_cachestat 451
+__SYSCALL(__NR_cachestat, sys_cachestat)
+
 #undef __NR_syscalls
-#define __NR_syscalls 451
+#define __NR_syscalls 452
 
 /*
  * 32 bit systems traditionally used different
include/uapi/linux/mman.h +14 -0
index f55bc680b5b0..a246e11988d5 100644
@@ -4,6 +4,7 @@
 
 #include <asm/mman.h>
 #include <asm-generic/hugetlb_encode.h>
+#include <linux/types.h>
 
 #define MREMAP_MAYMOVE		1
 #define MREMAP_FIXED		2
@@ -41,4 +42,17 @@
 #define MAP_HUGE_2GB	HUGETLB_FLAG_ENCODE_2GB
 #define MAP_HUGE_16GB	HUGETLB_FLAG_ENCODE_16GB
 
+struct cachestat_range {
+	__u64 off;
+	__u64 len;
+};
+
+struct cachestat {
+	__u64 nr_cache;
+	__u64 nr_dirty;
+	__u64 nr_writeback;
+	__u64 nr_evicted;
+	__u64 nr_recently_evicted;
+};
+
 #endif /* _UAPI_LINUX_MMAN_H */
init/Kconfig +10 -0
index 32c24950c4ce..f7f65af4ee12 100644
@@ -1771,6 +1771,16 @@ config RSEQ
 
 	  If unsure, say Y.
 
+config CACHESTAT_SYSCALL
+	bool "Enable cachestat() system call" if EXPERT
+	default y
+	help
+	  Enable the cachestat system call, which queries the page cache
+	  statistics of a file (number of cached pages, dirty pages,
+	  pages marked for writeback, (recently) evicted pages).
+
+	  If unsure say Y here.
+
 config DEBUG_RSEQ
 	default n
 	bool "Enabled debugging of rseq() system call" if EXPERT
kernel/sys_ni.c +1 -0
index 860b2dcf3ac4..04bfb1e4d377 100644
@@ -299,6 +299,7 @@ COND_SYSCALL(set_mempolicy);
 COND_SYSCALL(migrate_pages);
 COND_SYSCALL(move_pages);
 COND_SYSCALL(set_mempolicy_home_node);
+COND_SYSCALL(cachestat);
 
 COND_SYSCALL(perf_event_open);
 COND_SYSCALL(accept4);
mm/filemap.c +172 -0

187 lines not on this page · raw message

Signature · 1 line
2.34.1
maintainer Acked-by on v13 2/3
#4 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

Quoted 88 lines · Nhat Pham

There is currently no good way to query the page cache state of large file sets and directory trees. There is mincore(), but it scales poorly:
the kernel writes out a lot of bitmap data that userspace has to aggregate, when the user really doesn not care about per-page information in that case. The user also needs to mmap and unmap each file as it goes along, which can be quite slow as well.

Some use cases where this information could come in handy:
* Allowing database to decide whether to perform an index scan or direct table queries based on the in-memory cache state of the index.
* Visibility into the writeback algorithm, for performance issues diagnostic.
* Workload-aware writeback pacing: estimating IO fulfilled by page cache (and IO to be done) within a range of a file, allowing for more frequent syncing when and where there is IO capacity, and batching when there is not.
* Computing memory usage of large files/directory trees, analogous to the du tool for disk usage.

More information about these use cases could be found in the following thread:

https://lore.kernel.org/lkml/[email protected]/

This patch implements a new syscall that queries cache state of a file and summarizes the number of cached pages, number of dirty pages, number of pages marked for writeback, number of (recently) evicted pages, etc. in a given range. Currently, the syscall is only wired in for x86 architecture.

NAME
cachestat - query the page cache statistics of a file.

SYNOPSIS

    #include <sys/mman.h>

    struct cachestat_range {
        __u64 off;
        __u64 len;
    };

    struct cachestat {
        __u64 nr_cache;
        __u64 nr_dirty;
        __u64 nr_writeback;
        __u64 nr_evicted;
        __u64 nr_recently_evicted;
    };

    int cachestat(unsigned int fd, struct cachestat_range *cstat_range,
        struct cachestat *cstat, unsigned int flags);

DESCRIPTION
cachestat() queries the number of cached pages, number of dirty pages, number of pages marked for writeback, number of evicted pages, number of recently evicted pages, in the bytes range given by off and len.

An evicted page is a page that is previously in the page cache but has been evicted since. A page is recently evicted if its last eviction was recent enough that its reentry to the cache would indicate that it is actively being used by the system, and that there is memory pressure on the system.

These values are returned in a cachestat struct, whose address is given by the cstat argument.

The off and len arguments must be non-negative integers. If len > 0, the queried range is [off, off + len]. If len == 0, we will query in the range from off to the end of the file.

The flags argument is unused for now, but is included for future extensibility. User should pass 0 (i.e no flag specified).

Currently, hugetlbfs is not supported.

Because the status of a page can change after cachestat() checks it but before it returns to the application, the returned values may contain stale information.

RETURN VALUE
On success, cachestat returns 0. On error, -1 is returned, and errno is set to indicate the error.

ERRORS
EFAULT cstat or cstat_args points to an invalid address.

Quoted 7 lines

EINVAL invalid flags.

EBADF invalid file descriptor.

EOPNOTSUPP file descriptor is of a hugetlbfs file

Thanks for persisting through the pain. This looks great to me now.

Like I've said before, I think this is sorely needed. The cache is frequently the biggest memory consumer in the system. We have a rich API for influencing it, but there is a glaring gap when it comes to introspection. It's difficult to design control loops without feedback. This proposes an intuitive, versatile and scalable interface to bridge that gap, and it integrates nicely with the existing VFS API for managing the cache. I would love to see this go in.

I'd also love for the `mu' tool you wrote to make it into coreutils eventually. It would make debugging memory consumption and writeback issues on live systems, especially with complex and/or multiple workloads, so much easier.

author maintainer
#5 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

Quoted 108 lines · Johannes Weiner
Quoted 88 lines · Nhat Pham

There is currently no good way to query the page cache state of large file sets and directory trees. There is mincore(), but it scales poorly:
the kernel writes out a lot of bitmap data that userspace has to aggregate, when the user really doesn not care about per-page information in that case. The user also needs to mmap and unmap each file as it goes along, which can be quite slow as well.

Some use cases where this information could come in handy:
* Allowing database to decide whether to perform an index scan or direct table queries based on the in-memory cache state of the index.
* Visibility into the writeback algorithm, for performance issues diagnostic.
* Workload-aware writeback pacing: estimating IO fulfilled by page cache (and IO to be done) within a range of a file, allowing for more frequent syncing when and where there is IO capacity, and batching when there is not.
* Computing memory usage of large files/directory trees, analogous to the du tool for disk usage.

More information about these use cases could be found in the following thread:

https://lore.kernel.org/lkml/[email protected]/

This patch implements a new syscall that queries cache state of a file and summarizes the number of cached pages, number of dirty pages, number of pages marked for writeback, number of (recently) evicted pages, etc. in a given range. Currently, the syscall is only wired in for x86 architecture.

NAME
cachestat - query the page cache statistics of a file.

SYNOPSIS

    #include <sys/mman.h>

    struct cachestat_range {
        __u64 off;
        __u64 len;
    };

    struct cachestat {
        __u64 nr_cache;
        __u64 nr_dirty;
        __u64 nr_writeback;
        __u64 nr_evicted;
        __u64 nr_recently_evicted;
    };

    int cachestat(unsigned int fd, struct cachestat_range *cstat_range,
        struct cachestat *cstat, unsigned int flags);

DESCRIPTION
cachestat() queries the number of cached pages, number of dirty pages, number of pages marked for writeback, number of evicted pages, number of recently evicted pages, in the bytes range given by off and len.

An evicted page is a page that is previously in the page cache but has been evicted since. A page is recently evicted if its last eviction was recent enough that its reentry to the cache would indicate that it is actively being used by the system, and that there is memory pressure on the system.

These values are returned in a cachestat struct, whose address is given by the cstat argument.

The off and len arguments must be non-negative integers. If len > 0, the queried range is [off, off + len]. If len == 0, we will query in the range from off to the end of the file.

The flags argument is unused for now, but is included for future extensibility. User should pass 0 (i.e no flag specified).

Currently, hugetlbfs is not supported.

Because the status of a page can change after cachestat() checks it but before it returns to the application, the returned values may contain stale information.

RETURN VALUE
On success, cachestat returns 0. On error, -1 is returned, and errno is set to indicate the error.

ERRORS
EFAULT cstat or cstat_args points to an invalid address.

Quoted 7 lines

EINVAL invalid flags.

EBADF invalid file descriptor.

EOPNOTSUPP file descriptor is of a hugetlbfs file

Thanks for persisting through the pain. This looks great to me now.

Like I've said before, I think this is sorely needed. The cache is frequently the biggest memory consumer in the system. We have a rich API for influencing it, but there is a glaring gap when it comes to introspection. It's difficult to design control loops without feedback. This proposes an intuitive, versatile and scalable interface to bridge that gap, and it integrates nicely with the existing VFS API for managing the cache. I would love to see this go in.

Quoted 4 lines

I'd also love for the `mu' tool you wrote to make it into coreutils eventually. It would make debugging memory consumption and writeback issues on live systems, especially with complex and/or multiple workloads, so much easier.

I'd love to share this too! Let me clean it up and submit it separately.

Quoted 2 lines
#6 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

In reply to Nhat Pham

Hi Nhat,

Quoted 90 lines · Nhat Pham

There is currently no good way to query the page cache state of large file sets and directory trees. There is mincore(), but it scales poorly:
the kernel writes out a lot of bitmap data that userspace has to aggregate, when the user really doesn not care about per-page information in that case. The user also needs to mmap and unmap each file as it goes along, which can be quite slow as well.

Some use cases where this information could come in handy:
* Allowing database to decide whether to perform an index scan or direct table queries based on the in-memory cache state of the index.
* Visibility into the writeback algorithm, for performance issues diagnostic.
* Workload-aware writeback pacing: estimating IO fulfilled by page cache (and IO to be done) within a range of a file, allowing for more frequent syncing when and where there is IO capacity, and batching when there is not.
* Computing memory usage of large files/directory trees, analogous to the du tool for disk usage.

More information about these use cases could be found in the following thread:

https://lore.kernel.org/lkml/[email protected]/

This patch implements a new syscall that queries cache state of a file and summarizes the number of cached pages, number of dirty pages, number of pages marked for writeback, number of (recently) evicted pages, etc. in a given range. Currently, the syscall is only wired in for x86 architecture.

NAME
cachestat - query the page cache statistics of a file.

SYNOPSIS

    #include <sys/mman.h>

    struct cachestat_range {
        __u64 off;
        __u64 len;
    };

    struct cachestat {
        __u64 nr_cache;
        __u64 nr_dirty;
        __u64 nr_writeback;
        __u64 nr_evicted;
        __u64 nr_recently_evicted;
    };

    int cachestat(unsigned int fd, struct cachestat_range *cstat_range,
        struct cachestat *cstat, unsigned int flags);

DESCRIPTION
cachestat() queries the number of cached pages, number of dirty pages, number of pages marked for writeback, number of evicted pages, number of recently evicted pages, in the bytes range given by off and len.

An evicted page is a page that is previously in the page cache but has been evicted since. A page is recently evicted if its last eviction was recent enough that its reentry to the cache would indicate that it is actively being used by the system, and that there is memory pressure on the system.

These values are returned in a cachestat struct, whose address is given by the cstat argument.

The off and len arguments must be non-negative integers. If len > 0, the queried range is [off, off + len]. If len == 0, we will query in the range from off to the end of the file.

The flags argument is unused for now, but is included for future extensibility. User should pass 0 (i.e no flag specified).

Currently, hugetlbfs is not supported.

Because the status of a page can change after cachestat() checks it but before it returns to the application, the returned values may contain stale information.

RETURN VALUE
On success, cachestat returns 0. On error, -1 is returned, and errno is set to indicate the error.

ERRORS
EFAULT cstat or cstat_args points to an invalid address.

EINVAL invalid flags.

Quoted 8 lines

EBADF invalid file descriptor.

EOPNOTSUPP file descriptor is of a hugetlbfs file

---
 arch/x86/entry/syscalls/syscall_32.tbl |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl |   1 +

This should be wired up on each and every architecture. Currently we're getting

<stdin>:1567:2: warning: #warning syscall cachestat not implemented [-Wcpp]

in linux-next for all the missing architectures.

Gr{oetje,eeting}s,

Geert

Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
author maintainer
#7 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

Quoted 103 lines · Geert Uytterhoeven

Hi Nhat,

Quoted 90 lines · Nhat Pham

There is currently no good way to query the page cache state of large file sets and directory trees. There is mincore(), but it scales poorly:
the kernel writes out a lot of bitmap data that userspace has to aggregate, when the user really doesn not care about per-page information in that case. The user also needs to mmap and unmap each file as it goes along, which can be quite slow as well.

Some use cases where this information could come in handy:
* Allowing database to decide whether to perform an index scan or direct table queries based on the in-memory cache state of the index.
* Visibility into the writeback algorithm, for performance issues diagnostic.
* Workload-aware writeback pacing: estimating IO fulfilled by page cache (and IO to be done) within a range of a file, allowing for more frequent syncing when and where there is IO capacity, and batching when there is not.
* Computing memory usage of large files/directory trees, analogous to the du tool for disk usage.

More information about these use cases could be found in the following thread:

https://lore.kernel.org/lkml/[email protected]/

This patch implements a new syscall that queries cache state of a file and summarizes the number of cached pages, number of dirty pages, number of pages marked for writeback, number of (recently) evicted pages, etc. in a given range. Currently, the syscall is only wired in for x86 architecture.

NAME
cachestat - query the page cache statistics of a file.

SYNOPSIS

    #include <sys/mman.h>

    struct cachestat_range {
        __u64 off;
        __u64 len;
    };

    struct cachestat {
        __u64 nr_cache;
        __u64 nr_dirty;
        __u64 nr_writeback;
        __u64 nr_evicted;
        __u64 nr_recently_evicted;
    };

    int cachestat(unsigned int fd, struct cachestat_range *cstat_range,
        struct cachestat *cstat, unsigned int flags);

DESCRIPTION
cachestat() queries the number of cached pages, number of dirty pages, number of pages marked for writeback, number of evicted pages, number of recently evicted pages, in the bytes range given by off and len.

An evicted page is a page that is previously in the page cache but has been evicted since. A page is recently evicted if its last eviction was recent enough that its reentry to the cache would indicate that it is actively being used by the system, and that there is memory pressure on the system.

These values are returned in a cachestat struct, whose address is given by the cstat argument.

The off and len arguments must be non-negative integers. If len > 0, the queried range is [off, off + len]. If len == 0, we will query in the range from off to the end of the file.

The flags argument is unused for now, but is included for future extensibility. User should pass 0 (i.e no flag specified).

Currently, hugetlbfs is not supported.

Because the status of a page can change after cachestat() checks it but before it returns to the application, the returned values may contain stale information.

RETURN VALUE
On success, cachestat returns 0. On error, -1 is returned, and errno is set to indicate the error.

ERRORS
EFAULT cstat or cstat_args points to an invalid address.

EINVAL invalid flags.

Quoted 8 lines

EBADF invalid file descriptor.

EOPNOTSUPP file descriptor is of a hugetlbfs file

---
 arch/x86/entry/syscalls/syscall_32.tbl |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl |   1 +
Quoted 6 lines

This should be wired up on each and every architecture. Currently we're getting

<stdin>:1567:2: warning: #warning syscall cachestat not implemented [-Wcpp]

in linux-next for all the missing architectures.

Hi Geert,

I saw that there are several instances where we have separate patches to wire up a syscall to these architectures, so I was doing something similar.

For e.g:

ARM: wire up process_vm_writev and process_vm_readv syscalls (e5489847d6fc0ff176048b6e1cf5034507bf703a)

MIPS: Hook up process_vm_readv and process_vm_writev system calls. (8ff8584e51d4d3fbe08ede413c4a221223766323)

As for these non-x86 architecture wiring patches, I can give it a shot and cross-compile to see if it builds, but I have limited abilities for runtime tests as I don't have machines with these architectures. I would really appreciate it if there are arch people that could help wire it up.

(cc-ing linux-arch as well)

Quoted 11 lines

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds

maintainer
#8 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

In reply to Geert Uytterhoeven
Quoted 9 lines · On Thu, 4 May 2023 19:26:11 +0200 Geert Uytterhoeven <[email protected]>…
Quoted 2 lines
 arch/x86/entry/syscalls/syscall_32.tbl |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl |   1 +

This should be wired up on each and every architecture. Currently we're getting

<stdin>:1567:2: warning: #warning syscall cachestat not implemented [-Wcpp]

in linux-next for all the missing architectures.

Is that wise? We risk adding a syscall to an architecture without the arch maintainers and testers even knowing about it.

The compile-time nag is there to inform the arch maintainers that a new syscall is available and that they should wire it up, run the selftest and then ship the code if they're happy with the result.

maintainer
#9 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

Quoted 11 lines · Andrew Morton
Quoted 8 lines · On Thu, 4 May 2023 19:26:11 +0200 Geert Uytterhoeven <[email protected]>…
Quoted 2 lines
 arch/x86/entry/syscalls/syscall_32.tbl |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl |   1 +

This should be wired up on each and every architecture. Currently we're getting

<stdin>:1567:2: warning: #warning syscall cachestat not implemented [-Wcpp]

Quoted 8 lines
Quoted 1 line

in linux-next for all the missing architectures.

Is that wise? We risk adding a syscall to an architecture without the arch maintainers and testers even knowing about it.

The compile-time nag is there to inform the arch maintainers that a new syscall is available and that they should wire it up, run the selftest and then ship the code if they're happy with the result.

The usual approach is for the author of a new syscall to include a patch with all the architecture specific changes and Cc the architecture maintainers for that.

Note that half the architectures get the entry from include/uapi/asm-generic/unistd.h, so adding it there does not necessarily trigger adding each maintainer from scripts/get_maintainer.pl.

The only real risk in adding a new syscall is passing __u64 register arguments that behave differently across architectures, or using pointers to data structures that require a compat handler on some architectures. I watch out for those as they get sent to me or the linux-arch list, and this one is fine.

Arnd

author maintainer
#10 lore raw

Re: [PATCH v13 2/3] cachestat: implement cachestat syscall

Quoted 31 lines · Arnd Bergmann
Quoted 11 lines · Andrew Morton
Quoted 8 lines · On Thu, 4 May 2023 19:26:11 +0200 Geert Uytterhoeven <[email protected]>…
Quoted 2 lines
 arch/x86/entry/syscalls/syscall_32.tbl |   1 +
 arch/x86/entry/syscalls/syscall_64.tbl |   1 +

This should be wired up on each and every architecture. Currently we're getting

<stdin>:1567:2: warning: #warning syscall cachestat not implemented [-Wcpp]

Quoted 8 lines
Quoted 1 line

in linux-next for all the missing architectures.

Is that wise? We risk adding a syscall to an architecture without the arch maintainers and testers even knowing about it.

The compile-time nag is there to inform the arch maintainers that a new syscall is available and that they should wire it up, run the selftest and then ship the code if they're happy with the result.

The usual approach is for the author of a new syscall to include a patch with all the architecture specific changes and Cc the architecture maintainers for that.

Note that half the architectures get the entry from include/uapi/asm-generic/unistd.h, so adding it there does not necessarily trigger adding each maintainer from scripts/get_maintainer.pl.

Quoted 8 lines

The only real risk in adding a new syscall is passing __u64 register arguments that behave differently across architectures, or using pointers to data structures that require a compat handler on some architectures. I watch out for those as they get sent to me or the linux-arch list, and this one is fine.

Arnd

I took a stab at wiring the new syscall in this follow-up patch:

https://lore.kernel.org/lkml/[email protected]/

Let me know if I missed something! Review and/or suggestion is very much appreciated.

author maintainer
#11 lore raw

PATCH v13 3/3 selftests: Add selftests for cachestat

In reply to Nhat Pham

Test cachestat on a newly created file, /dev/ files, and /proc/ files. Also test on a shmem file (which can also be tested with huge pages since tmpfs supports huge pages).

---
 MAINTAINERS                                   |   7 +
 tools/testing/selftests/Makefile              |   1 +
 tools/testing/selftests/cachestat/.gitignore  |   2 +
 tools/testing/selftests/cachestat/Makefile    |   8 +
 .../selftests/cachestat/test_cachestat.c      | 258 ++++++++++++++++++
 5 files changed, 276 insertions(+)
 create mode 100644 tools/testing/selftests/cachestat/.gitignore
 create mode 100644 tools/testing/selftests/cachestat/Makefile
 create mode 100644 tools/testing/selftests/cachestat/test_cachestat.c
MAINTAINERS +7 -0
index 32772c383ab7..a02946fdd680 100644
@@ -4510,6 +4510,13 @@ S:	Supported
 F:	Documentation/filesystems/caching/cachefiles.rst
 F:	fs/cachefiles/
 
+CACHESTAT: PAGE CACHE STATS FOR A FILE
+M:	Nhat Pham <[email protected]>
+M:	Johannes Weiner <[email protected]>
+L:	[email protected]
+S:	Maintained
+F:	tools/testing/selftests/cachestat/test_cachestat.c
+
 CADENCE MIPI-CSI2 BRIDGES
 M:	Maxime Ripard <[email protected]>
 L:	[email protected]
tools/testing/selftests/Makefile +1 -0
index 97dcdaa656f6..5994e56e1214 100644
@@ -4,6 +4,7 @@ TARGETS += amd-pstate
 TARGETS += arm64
 TARGETS += bpf
 TARGETS += breakpoints
+TARGETS += cachestat
 TARGETS += capabilities
 TARGETS += cgroup
 TARGETS += clone3
tools/testing/selftests/cachestat/.gitignore new file +2 -0
new file mode 100644
index 000000000000..d6c30b43a4bb
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: GPL-2.0-only
+test_cachestat
tools/testing/selftests/cachestat/Makefile new file +8 -0
new file mode 100644
index 000000000000..fca73aaa7d14
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: GPL-2.0
+TEST_GEN_PROGS := test_cachestat
+
+CFLAGS += $(KHDR_INCLUDES)
+CFLAGS += -Wall
+CFLAGS += -lrt
+
+include ../lib.mk
tools/testing/selftests/cachestat/test_cachestat.c new file +258 -0

258 lines not on this page · raw message

Signature · 1 line
2.34.1
maintainer Acked-by on v13 3/3
#12 lore raw

Re: [PATCH v13 3/3] selftests: Add selftests for cachestat

Quoted 5 lines · Nhat Pham

Test cachestat on a newly created file, /dev/ files, and /proc/ files. Also test on a shmem file (which can also be tested with huge pages since tmpfs supports huge pages).

*and a directory

Looks good to me. It covers a good set of real cases and weird cases.

#13 lore raw

Re: [PATCH v13 3/3] selftests: Add selftests for cachestat

In reply to Nhat Pham
Quoted 5 lines · Nhat Pham

Test cachestat on a newly created file, /dev/ files, and /proc/ files. Also test on a shmem file (which can also be tested with huge pages since tmpfs supports huge pages).

...

Quoted 30 lines
tools/testing/selftests/cachestat/test_cachestat.c new file +24 -0
new file mode 100644
index 000000000000..c3823b809c25
@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: GPL-2.0
+#define _GNU_SOURCE
+
+#include <stdio.h>
+#include <stdbool.h>
+#include <linux/kernel.h>
+#include <linux/mman.h>
+#include <sys/mman.h>
+#include <sys/shm.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <string.h>
+#include <fcntl.h>
+#include <errno.h>
+
+#include "../kselftest.h"
+
+static const char * const dev_files[] = {
+	"/dev/zero", "/dev/null", "/dev/urandom",
+	"/proc/version", "/proc"
+};
+static const int cachestat_nr = 451;
+
+void print_cachestat(struct cachestat *cs)

tools/testing/selftests/cachestat/test_cachestat.c line 34

Quoted 10 lines
tools/testing/selftests/cachestat/test_cachestat.c new file +10 -0
+{
+	ksft_print_msg(
+	"Using cachestat: Cached: %lu, Dirty: %lu, Writeback: %lu, Evicted: %lu, Recently Evicted: %lu\n",
+	cs->nr_cache, cs->nr_dirty, cs->nr_writeback,
+	cs->nr_evicted, cs->nr_recently_evicted);
+}
+
+bool write_exactly(int fd, size_t filesize)
+{
+	char data[filesize];

On kernels with 64K pages (powerpc at least), this tries to allocate 64MB on the stack which segfaults.

Allocating data with malloc avoids the problem and allows the test to pass.

Looks like this commit is still in mm-unstable, so maybe Andrew can squash the incremental diff below in, if it looks OK to you. The diff is a bit big because I unindented the body of the function.

cheers

tools/testing/selftests/cachestat/test_cachestat.c +37 -26
index 9be2262e5c17..54d09b820ed4 100644
@@ -31,48 +31,59 @@ void print_cachestat(struct cachestat *cs)
 
 bool write_exactly(int fd, size_t filesize)
 {
-	char data[filesize];
-	bool ret = true;
 	int random_fd = open("/dev/urandom", O_RDONLY);
+	char *cursor, *data;
+	int remained;
+	bool ret;
 
 	if (random_fd < 0) {
 		ksft_print_msg("Unable to access urandom.\n");
 		ret = false;
 		goto out;
-	} else {
-		int remained = filesize;
-		char *cursor = data;
+	}
 
-		while (remained) {
-			ssize_t read_len = read(random_fd, cursor, remained);
+	data = malloc(filesize);
+	if (!data) {
+		ksft_print_msg("Unable to allocate data.\n");
+		ret = false;
+		goto close_random_fd;
+	}
 
-			if (read_len <= 0) {
-				ksft_print_msg("Unable to read from urandom.\n");
-				ret = false;
-				goto close_random_fd;
-			}
+	remained = filesize;
+	cursor = data;
 
-			remained -= read_len;
-			cursor += read_len;
+	while (remained) {
+		ssize_t read_len = read(random_fd, cursor, remained);
+
+		if (read_len <= 0) {
+			ksft_print_msg("Unable to read from urandom.\n");
+			ret = false;
+			goto out_free_data;
 		}
 
-		/* write random data to fd */
-		remained = filesize;
-		cursor = data;
-		while (remained) {
-			ssize_t write_len = write(fd, cursor, remained);
+		remained -= read_len;
+		cursor += read_len;
+	}
 
-			if (write_len <= 0) {
-				ksft_print_msg("Unable write random data to file.\n");
-				ret = false;
-				goto close_random_fd;
-			}
+	/* write random data to fd */
+	remained = filesize;
+	cursor = data;
+	while (remained) {
+		ssize_t write_len = write(fd, cursor, remained);
 
-			remained -= write_len;
-			cursor += write_len;
+		if (write_len <= 0) {
+			ksft_print_msg("Unable write random data to file.\n");
+			ret = false;
+			goto out_free_data;
 		}
+
+		remained -= write_len;
+		cursor += write_len;
 	}
 
+	ret = true;
+out_free_data:
+	free(data);
 close_random_fd:
 	close(random_fd);
 out:
author maintainer Acked-by
#14 lore raw

Re: [PATCH v13 3/3] selftests: Add selftests for cachestat

Quoted 143 lines · Michael Ellerman
Quoted 5 lines · Nhat Pham

Test cachestat on a newly created file, /dev/ files, and /proc/ files. Also test on a shmem file (which can also be tested with huge pages since tmpfs supports huge pages).

...

Quoted 30 lines
tools/testing/selftests/cachestat/test_cachestat.c new file +24 -0
new file mode 100644
index 000000000000..c3823b809c25
@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: GPL-2.0
+#define _GNU_SOURCE
+
+#include <stdio.h>
+#include <stdbool.h>
+#include <linux/kernel.h>
+#include <linux/mman.h>
+#include <sys/mman.h>
+#include <sys/shm.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <string.h>
+#include <fcntl.h>
+#include <errno.h>
+
+#include "../kselftest.h"
+
+static const char * const dev_files[] = {
+     "/dev/zero", "/dev/null", "/dev/urandom",
+     "/proc/version", "/proc"
+};
+static const int cachestat_nr = 451;
+
+void print_cachestat(struct cachestat *cs)

tools/testing/selftests/cachestat/test_cachestat.c line 34

Quoted 10 lines
tools/testing/selftests/cachestat/test_cachestat.c new file +10 -0
+{
+     ksft_print_msg(
+     "Using cachestat: Cached: %lu, Dirty: %lu, Writeback: %lu, Evicted: %lu, Recently Evicted: %lu\n",
+     cs->nr_cache, cs->nr_dirty, cs->nr_writeback,
+     cs->nr_evicted, cs->nr_recently_evicted);
+}
+
+bool write_exactly(int fd, size_t filesize)
+{
+     char data[filesize];

On kernels with 64K pages (powerpc at least), this tries to allocate 64MB on the stack which segfaults.

Allocating data with malloc avoids the problem and allows the test to pass.

Looks like this commit is still in mm-unstable, so maybe Andrew can squash the incremental diff below in, if it looks OK to you. The diff is a bit big because I unindented the body of the function.

cheers

tools/testing/selftests/cachestat/test_cachestat.c +32 -26
index 9be2262e5c17..54d09b820ed4 100644
@@ -31,48 +31,59 @@ void print_cachestat(struct cachestat *cs)
 
 bool write_exactly(int fd, size_t filesize)
 {
-       char data[filesize];
-       bool ret = true;
        int random_fd = open("/dev/urandom", O_RDONLY);
+       char *cursor, *data;
+       int remained;
+       bool ret;
 
        if (random_fd < 0) {
                ksft_print_msg("Unable to access urandom.\n");
                ret = false;
                goto out;
-       } else {
-               int remained = filesize;
-               char *cursor = data;
+       }
 
-               while (remained) {
-                       ssize_t read_len = read(random_fd, cursor, remained);
+       data = malloc(filesize);
+       if (!data) {
+               ksft_print_msg("Unable to allocate data.\n");
+               ret = false;
+               goto close_random_fd;
+       }
 
-                       if (read_len <= 0) {
-                               ksft_print_msg("Unable to read from urandom.\n");
-                               ret = false;
-                               goto close_random_fd;
-                       }
+       remained = filesize;
+       cursor = data;
 
-                       remained -= read_len;
-                       cursor += read_len;
+       while (remained) {
+               ssize_t read_len = read(random_fd, cursor, remained);
+
+               if (read_len <= 0) {
+                       ksft_print_msg("Unable to read from urandom.\n");
+                       ret = false;
+                       goto out_free_data;
                }
 
-               /* write random data to fd */
-               remained = filesize;
-               cursor = data;
-               while (remained) {
-                       ssize_t write_len = write(fd, cursor, remained);
+               remained -= read_len;
+               cursor += read_len;
+       }
 
-                       if (write_len <= 0) {
-                               ksft_print_msg("Unable write random data to file.\n");
-                               ret = false;
-                               goto close_random_fd;
-                       }
+       /* write random data to fd */
+       remained = filesize;
+       cursor = data;
+       while (remained) {
+               ssize_t write_len = write(fd, cursor, remained);
 
-                       remained -= write_len;
-                       cursor += write_len;
+               if (write_len <= 0) {
+                       ksft_print_msg("Unable write random data to file.\n");
+                       ret = false;
+                       goto out_free_data;
                }
+

tools/testing/selftests/cachestat/test_cachestat.c void print_cachestat(struct cachestat *cs) · line 89

Quoted 10 lines
tools/testing/selftests/cachestat/test_cachestat.c +5 -0
+               remained -= write_len;
+               cursor += write_len;
        }
 
+       ret = true;
+out_free_data:
+       free(data);
 close_random_fd:
        close(random_fd);
 out:

Oh this is nice! I had to make a similar fix in another test of mine, but forgot about it in this context.

LGTM. For verification, I have applied the diff and test on my own local setup. Things still pass.