Merge branch 'master'

[linux-2.6] / Documentation / filesystems / fuse.txt

diff --git a/Documentation/filesystems/fuse.txt b/Documentation/filesystems/fuse.txt
index 83f96cf56960344f1911b8107e1055511ca9cc69..33f74310d161bac64f1c4d997842c5769b64759f 100644 (file)
--- a/Documentation/filesystems/fuse.txt
+++ b/Documentation/filesystems/fuse.txt
@@ -80,37 +80,67 @@ Mount options
   allowed to root, but this restriction can be removed with a
   (userspace) configuration option.
 
-'kernel_cache'
+'max_read=N'
 
-  This option disables flushing the cache of the file contents on
-  every open().  This should only be enabled on filesystems, where the
-  file data is never changed externally (not through the mounted FUSE
-  filesystem).  Thus it is not suitable for network filesystems and
-  other "intermediate" filesystems.
+  With this option the maximum size of read operations can be set.
+  The default is infinite.  Note that the size of read requests is
+  limited anyway to 32 pages (which is 128kbyte on i386).
 
-  NOTE: if this option is not specified (and neither 'direct_io') data
-  is still cached after the open(), so a read() system call will not
-  always initiate a read operation.
+Sysfs
+~~~~~
 
-'direct_io'
+FUSE sets up the following hierarchy in sysfs:
 
-  This option disables the use of page cache (file content cache) in
-  the kernel for this filesystem.  This has several affects:
+  /sys/fs/fuse/connections/N/
 
-     - Each read() or write() system call will initiate one or more
-       read or write operations, data will not be cached in the
-       kernel.
+where N is an increasing number allocated to each new connection.
 
-     - The return value of the read() and write() system calls will
-       correspond to the return values of the read and write
-       operations.  This is useful for example if the file size is not
-       known in advance (before reading it).
+For each connection the following attributes are defined:
 
-'max_read=N'
+ 'waiting'
 
-  With this option the maximum size of read operations can be set.
-  The default is infinite.  Note that the size of read requests is
-  limited anyway to 32 pages (which is 128kbyte on i386).
+  The number of requests which are waiting to be transfered to
+  userspace or being processed by the filesystem daemon.  If there is
+  no filesystem activity and 'waiting' is non-zero, then the
+  filesystem is hung or deadlocked.
+
+ 'abort'
+
+  Writing anything into this file will abort the filesystem
+  connection.  This means that all waiting requests will be aborted an
+  error returned for all aborted and new requests.
+
+Only a privileged user may read or write these attributes.
+
+Aborting a filesystem connection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to get into certain situations where the filesystem is
+not responding.  Reasons for this may be:
+
+  a) Broken userspace filesystem implementation
+
+  b) Network connection down
+
+  c) Accidental deadlock
+
+  d) Malicious deadlock
+
+(For more on c) and d) see later sections)
+
+In either of these cases it may be useful to abort the connection to
+the filesystem.  There are several ways to do this:
+
+  - Kill the filesystem daemon.  Works in case of a) and b)
+
+  - Kill the filesystem daemon and all users of the filesystem.  Works
+    in all cases except some malicious deadlocks
+
+  - Use forced umount (umount -f).  Works in all cases but only if
+    filesystem is still attached (it hasn't been lazy unmounted)
+
+  - Abort filesystem through the sysfs interface.  Most powerful
+    method, always works.
 
 How do non-privileged mounts work?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -339,3 +369,10 @@ faulted with get_user_pages().  The 'req->locked' flag indicates
 when the copy is taking place, and interruption is delayed until
 this flag is unset.
 
+Scenario 3 - Tricky deadlock with asynchronous read
+---------------------------------------------------
+
+The same situation as above, except thread-1 will wait on page lock
+and hence it will be uninterruptible as well.  The solution is to
+abort the connection with forced umount (if mount is attached) or
+through the abort attribute in sysfs.