fs: Allow overlays to revalidate files from the upper fs.

Previously, an overlay would panic if either the upper or lower fs required
revalidation for a given Dirent. Now, we allow revalidation from the upper
file, but not the lower.

If a cached overlay inode does need revalidation (because the upper needs
revalidation), then the entire overlay Inode will be discarded and a new
overlay Inode will be built with a fresh copy of the upper file.

As a side effect of this change, Revalidate must take an Inode instead of a
Dirent, since an overlay needs to revalidate individual Inodes.

PiperOrigin-RevId: 208293638
Change-Id: Ic8f8d1ffdc09114721745661a09522b54420c5f1

1 files changed, 12 insertions, 0 deletions

diff --git a/pkg/sentry/fs/README.md b/pkg/sentry/fs/README.md
index 76638cdae..7680187f4 100644
--- a/pkg/sentry/fs/README.md
+++ b/pkg/sentry/fs/README.md
@@ -193,6 +193,18 @@ interface. It multiplexes between upper and lower directory memory mappings and
 stores a copy of memory references so they can be transferred to the upper
 directory `fs.Mappable` when the file is copied up.
 
+The lower filesystem in an overlay may contain another (nested) overlay, but the
+upper filesystem may not contain another overlay. In other words, nested
+overlays form a tree structure that only allows branching in the lower
+filesystem.
+
+Caching decisions in the overlay are delegated to the upper filesystem, meaning
+that the Keep and Revalidate methods on the overlay return the same values as
+the upper filesystem. A small wrinkle is that the lower filesystem is not
+allowed to return `true` from Revalidate, as the overlay can not reload inodes
+from the lower filesystem. A lower filesystem that does return `true` from
+Revalidate will trigger a panic.
+
 The `fs.Inode` also holds a reference to a `fs.MountedFilesystem` that
 normalizes across the mounted filesystem state of the upper and lower
 directories.