[PATCH 17/21] Unionfs: Documentation update regarding overlapping branches and new lookup code

Josef 'Jeff' Sipek
2007-05-24T00:39:47Z

Added detailed comment and updated documentation to explain why overlapping
branches are disallowed, and better explain the cache coherency issues.

Signed-off-by: Erez Zadok <ezk@cs.sunysb.edu>
Signed-off-by: Josef 'Jeff' Sipek <jsipek@cs.sunysb.edu>
---
Documentation/filesystems/unionfs/issues.txt | 16 ++++++++--------
fs/unionfs/main.c | 16 +++++++++++++++-
2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/Documentation/filesystems/unionfs/issues.txt b/Documentation/filesystems/unionfs/issues.txt
index a434fee..c634604 100644
--- a/Documentation/filesystems/unionfs/issues.txt
+++ b/Documentation/filesystems/unionfs/issues.txt
@@ -5,14 +5,14 @@ KNOWN Unionfs 2.0 ISSUES:
This means we can't reliably detect a read-only NFS export.

2. Modifying a Unionfs branch directly, while the union is mounted, is
- currently unsupported. We have tested Unionfs under such conditions, and
- fixed any bugs we found (Unionfs comes with an extensive regression test
- suite). However, it may still be possible that changes made to lower
- branches directly could cause cache incoherency which, in the worst case,
- may case an oops. We are currently addressing this problem for Unionfs
- and also generically for all stackable file systems, by handing mmap and
- introducing small VFS/MM changes that would allow a file system to handle
- cache coherency correctly.
+ currently unsupported, because it could cause a cache incoherency between
+ the union layer and the lower file systems (for that reason, Unionfs
+ currently prohibits using branches which overlap with each other, even
+ partially). We have tested Unionfs under such conditions, and fixed any
+ bugs we found (Unionfs comes with an extensive regression test suite).
+ However, it may still be possible that changes made to lower branches
+ directly could cause cache incoherency which, in the worst case, may case
+ an oops.

Unionfs 2.0 has a temporary workaround for this. You can force Unionfs
to increase the superblock generation number, and hence purge all cached
diff --git a/fs/unionfs/main.c b/fs/unionfs/main.c
index 84d3bf5..a9ad445 100644
--- a/fs/unionfs/main.c
+++ b/fs/unionfs/main.c
@@ -351,7 +351,21 @@ static int parse_dirs_option(struct super_block *sb, struct unionfs_dentry_info

BUG_ON(branches != (hidden_root_info->bend + 1));

- /* ensure that no overlaps exist in the branches */
+ /*
+ * Ensure that no overlaps exist in the branches.
+ *
+ * This test is required because the Linux kernel has no support
+ * currently for ensuring coherency between stackable layers and
+ * branches. If we were to allow overlapping branches, it would be
+ * possible, for example, to delete a file via one branch, which
+ * would not be reflected in another branch. Such incoherency could
+ * lead to inconsistencies and even kernel oopses. Rather than
+ * implement hacks to work around some of these cache-coherency
+ * problems, we prevent branch overlapping, for now. A complete
+ * solution will involve proper kernel/VFS support for cache
+ * coherency, at which time we could safely remove this
+ * branch-overlapping test.
+ */
for (i = 0; i < branches; i++) {
for (j = i + 1; j < branches; j++) {
dent1 = hidden_root_info->lower_paths[i].dentry;
--
1.5.2.rc1.165.gaf9b