[PATCH] selftests/cachestat: add overlayfs test cases

From: Pavel Tikhomirov

Date: Thu Nov 19 2026 - 13:34:51 EST


Run cachestat() on overlayfs files in four variants. The file is written
either to the lower dir of an overlayfs or through its mount, so its
page cache is in the lower or in the upper dir. Then it is opened
read-only, so it is not copied up, and checked:

- through the overlayfs mount: the page cache is one stacking level
down;
- through a second overlayfs mount, which has the first one's merged dir
as its lower dir: the page cache is two stacking levels down.

Overlayfs does not cache file data in its own inodes, so cachestat()
sees the pages only if it is forwarded to the real file.

Add a check_cached argument to test_cachestat() to check the pages of a
file the test did not write itself, and bump NR_TESTS to the actual
number of tests (it was 9 while ten were already run).

The test rework and the changelog were drafted with the help of an AI
coding assistant (Claude); the result was reviewed and tested by me.

Link: https://lore.kernel.org/r/20261118123105.1247627-1-amir73il@xxxxxxxxx/
Signed-off-by: Pavel Tikhomirov <ptikhomirov@xxxxxxxxxxxxx>
---
v2:
- Rework of patch 3/3 of v1 on top of Amir's ->f_real() patch; the
->cachestat() file operation from patches 1-2 is replaced by it.
- Add lower file and nested overlayfs cases, and a check_cached argument
to test_cachestat().
v1: https://lore.kernel.org/r/20260623111533.2285005-1-ptikhomirov@xxxxxxxxxxxxx/

The nested cases pass only with Amir's ovl_f_real() recursion fix
(https://lore.kernel.org/r/CAOQ4uxjHwtZEHu9xMM6zg9niSgNdLXhAu65jA8Ai_SKVg-W2nw@xxxxxxxxxxxxxx/)
plus EXPORT_SYMBOL(__file_real) when overlayfs is a module; on Amir's v1
alone they fail with "Cached: 0".
---
.../selftests/cachestat/test_cachestat.c | 172 +++++++++++++++++-
1 file changed, 163 insertions(+), 9 deletions(-)

diff --git a/tools/testing/selftests/cachestat/test_cachestat.c b/tools/testing/selftests/cachestat/test_cachestat.c
index 542cd09cb4434..af8fa21c90ca1 100644
--- a/tools/testing/selftests/cachestat/test_cachestat.c
+++ b/tools/testing/selftests/cachestat/test_cachestat.c
@@ -4,27 +4,42 @@

#include <stdio.h>
#include <stdbool.h>
+#include <stdlib.h>
#include <linux/kernel.h>
#include <linux/magic.h>
#include <linux/mman.h>
#include <sys/mman.h>
+#include <sys/mount.h>
#include <sys/shm.h>
+#include <sys/stat.h>
#include <sys/syscall.h>
#include <sys/vfs.h>
#include <unistd.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
+#include <limits.h>

#include "kselftest.h"

-#define NR_TESTS 9
+#define NR_TESTS 14

static const char * const dev_files[] = {
"/dev/zero", "/dev/null", "/dev/urandom",
"/proc/version", "/proc"
};

+static const struct {
+ bool lower;
+ bool nested;
+ const char *desc;
+} ovl_tests[] = {
+ { false, false, "an overlayfs file" },
+ { false, true, "a nested overlayfs file" },
+ { true, false, "an overlayfs lower file" },
+ { true, true, "a nested overlayfs lower file" },
+};
+
void print_cachestat(struct cachestat *cs)
{
ksft_print_msg(
@@ -117,10 +132,14 @@ static bool is_on_tmpfs(int fd)
* Open/create the file at filename, (optionally) write random data to it
* (exactly num_pages), then test the cachestat syscall on this file.
*
+ * If write_random == true or check_cached == true, check that all num_pages
+ * pages of the file are cached or evicted.
+ *
* If test_fsync == true, fsync the file, then check the number of dirty
* pages.
*/
-static int test_cachestat(const char *filename, bool write_random, bool create,
+static int test_cachestat(const char *filename, bool write_random,
+ bool check_cached, bool create,
bool test_fsync, unsigned long num_pages,
int open_flags, mode_t open_mode)
{
@@ -161,7 +180,7 @@ static int test_cachestat(const char *filename, bool write_random, bool create,
} else {
print_cachestat(&cs);

- if (write_random) {
+ if (write_random || check_cached) {
if (cs.nr_cache + cs.nr_evicted != num_pages) {
ksft_print_msg(
"Total number of cached and evicted pages is off.\n");
@@ -294,6 +313,122 @@ bool run_cachestat_test(enum file_type type)
return ret;
}

+static int mount_overlayfs(const char *lowerdir, const char *upperdir,
+ const char *workdir, const char *merged)
+{
+ char opts[4 * PATH_MAX];
+
+ snprintf(opts, sizeof(opts), "lowerdir=%s,upperdir=%s,workdir=%s",
+ lowerdir, upperdir, workdir);
+ if (mount("overlay", merged, "overlay", 0, opts)) {
+ ksft_print_msg("Unable to mount overlayfs (need root?): %s\n",
+ strerror(errno));
+ return KSFT_SKIP;
+ }
+
+ return KSFT_PASS;
+}
+
+/*
+ * Write a file to an overlayfs, either directly to its lower dir (if lower)
+ * or through the overlayfs mount, so that its page cache is in the lower or
+ * upper dir. Then open the file read-only, so it is not copied up, through the
+ * overlayfs mount or, if nested, through a second overlayfs mount on top of it
+ * (using the first one's merged dir as its lower dir), and run cachestat on
+ * it. Overlayfs does not cache file data in its own inodes, so cachestat sees
+ * the pages only if it is forwarded one (or two, if nested) stacking levels
+ * down, to the page cache belonging to the real file.
+ */
+static int run_cachestat_overlayfs_test(bool lower, bool nested)
+{
+ char tmpl[] = "/tmp/cachestat_ovl.XXXXXX";
+ char lowerdir[PATH_MAX];
+ char upper1[PATH_MAX], work1[PATH_MAX], merged1[PATH_MAX];
+ char upper2[PATH_MAX], work2[PATH_MAX], merged2[PATH_MAX];
+ char cmd[PATH_MAX + 16], file[PATH_MAX + 16];
+ const char *write_path, *read_path;
+ char *base;
+ int ret;
+
+ base = mkdtemp(tmpl);
+ if (!base) {
+ ksft_print_msg("Unable to create overlayfs base dir: %s\n",
+ strerror(errno));
+ return KSFT_FAIL;
+ }
+
+ snprintf(lowerdir, sizeof(lowerdir), "%s/lower", base);
+ snprintf(upper1, sizeof(upper1), "%s/upper1", base);
+ snprintf(work1, sizeof(work1), "%s/work1", base);
+ snprintf(merged1, sizeof(merged1), "%s/merged1", base);
+ snprintf(upper2, sizeof(upper2), "%s/upper2", base);
+ snprintf(work2, sizeof(work2), "%s/work2", base);
+ snprintf(merged2, sizeof(merged2), "%s/merged2", base);
+
+ if (mkdir(lowerdir, 0755) || mkdir(upper1, 0755) ||
+ mkdir(work1, 0755) || mkdir(merged1, 0755) ||
+ mkdir(upper2, 0755) || mkdir(work2, 0755) ||
+ mkdir(merged2, 0755)) {
+ ksft_print_msg("Unable to create overlayfs dirs: %s\n",
+ strerror(errno));
+ ret = KSFT_FAIL;
+ goto cleanup;
+ }
+
+ if (lower)
+ write_path = lowerdir;
+ else
+ write_path = merged1;
+
+ if (nested)
+ read_path = merged2;
+ else
+ read_path = merged1;
+
+ snprintf(file, sizeof(file), "%s/cachestat", write_path);
+
+ /* Write the lower file before mounting overlayfs over it */
+ if (lower) {
+ ret = test_cachestat(file, true, false, false, false, 4,
+ O_CREAT | O_RDWR, 0600);
+ if (ret != KSFT_PASS)
+ goto cleanup;
+ }
+
+ ret = mount_overlayfs(lowerdir, upper1, work1, merged1);
+ if (ret != KSFT_PASS)
+ goto cleanup;
+
+ if (!lower) {
+ ret = test_cachestat(file, true, false, false, false, 4,
+ O_CREAT | O_RDWR, 0600);
+ if (ret != KSFT_PASS)
+ goto umount;
+ }
+
+ if (nested) {
+ ret = mount_overlayfs(merged1, upper2, work2, merged2);
+ if (ret != KSFT_PASS)
+ goto umount;
+ }
+
+ snprintf(file, sizeof(file), "%s/cachestat", read_path);
+ /* Look at that page cache through the overlayfs layer(s) */
+ ret = test_cachestat(file, false, true, false, false, 4,
+ O_RDONLY, 0);
+
+ if (nested)
+ umount(merged2);
+umount:
+ umount(merged1);
+cleanup:
+ /* Best-effort recursive cleanup of the temporary tree. */
+ snprintf(cmd, sizeof(cmd), "rm -rf %s", base);
+ if (system(cmd))
+ ksft_print_msg("Unable to clean up %s\n", base);
+ return ret;
+}
+
int main(void)
{
int ret;
@@ -317,8 +452,8 @@ int main(void)
for (int i = 0; i < 5; i++) {
const char *dev_filename = dev_files[i];

- if (test_cachestat(dev_filename, false, false, false,
- 4, O_RDONLY, 0400) == KSFT_PASS)
+ if (test_cachestat(dev_filename, false, false, false, false,
+ 4, O_RDONLY, 0400) == KSFT_PASS)
ksft_test_result_pass("cachestat works with %s\n", dev_filename);
else {
ksft_test_result_fail("cachestat fails with %s\n", dev_filename);
@@ -326,16 +461,16 @@ int main(void)
}
}

- if (test_cachestat("tmpfilecachestat", true, true,
- false, 4, O_CREAT | O_RDWR, 0600) == KSFT_PASS)
+ if (test_cachestat("tmpfilecachestat", true, false, true,
+ false, 4, O_CREAT | O_RDWR, 0600) == KSFT_PASS)
ksft_test_result_pass("cachestat works with a normal file\n");
else {
ksft_test_result_fail("cachestat fails with normal file\n");
ret = 1;
}

- switch (test_cachestat("tmpfilecachestat", true, true,
- true, 4, O_CREAT | O_RDWR, 0600)) {
+ switch (test_cachestat("tmpfilecachestat", true, false, true,
+ true, 4, O_CREAT | O_RDWR, 0600)) {
case KSFT_FAIL:
ksft_test_result_fail("cachestat fsync fails with normal file\n");
ret = KSFT_FAIL;
@@ -361,5 +496,24 @@ int main(void)
ksft_test_result_fail("cachestat fails with a mmap file\n");
ret = 1;
}
+
+ for (int i = 0; i < ARRAY_SIZE(ovl_tests); i++) {
+ const char *desc = ovl_tests[i].desc;
+
+ switch (run_cachestat_overlayfs_test(ovl_tests[i].lower,
+ ovl_tests[i].nested)) {
+ case KSFT_FAIL:
+ ksft_test_result_fail("cachestat fails with %s\n", desc);
+ ret = 1;
+ break;
+ case KSFT_PASS:
+ ksft_test_result_pass("cachestat works with %s\n", desc);
+ break;
+ case KSFT_SKIP:
+ ksft_test_result_skip("overlayfs not available for %s\n",
+ desc);
+ break;
+ }
+ }
return ret;
}
--
2.56.0