[src/trunk]: src/share/man/man9 Revamp fstrans(9) man page.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/fb5832b6a270
branches:  trunk
changeset: 807198:fb5832b6a270
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Tue Mar 31 15:47:50 2015 +0000

description:
Revamp fstrans(9) man page.

- Fix example: fstrans_start never fails and returns void.
- Add fstrans_mount/fstrans_unmount.
- Explain intent, not just mechanism.
- Add internal cross-references and redundant information from
  different callers' perspectives.

diffstat:

 share/man/man9/fstrans.9 |  280 ++++++++++++++++++++++++++++++++++------------
 1 files changed, 205 insertions(+), 75 deletions(-)

diffs (truncated from 373 to 300 lines):

diff -r cbbc043719dc -r fb5832b6a270 share/man/man9/fstrans.9
--- a/share/man/man9/fstrans.9  Tue Mar 31 11:59:41 2015 +0000
+++ b/share/man/man9/fstrans.9  Tue Mar 31 15:47:50 2015 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: fstrans.9,v 1.16 2013/09/17 19:58:03 wiz Exp $
+.\"     $NetBSD: fstrans.9,v 1.17 2015/03/31 15:47:50 riastradh Exp $
 .\"
 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd April 13, 2010
+.Dd March 31, 2015
 .Dt FSTRANS 9
 .Os
 .Sh NAME
@@ -46,9 +46,9 @@
 .In sys/mount.h
 .In sys/fstrans.h
 .Ft int
-.Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state"
-.Ft "enum fstrans_state"
-.Fn fstrans_getstate "struct mount *mp"
+.Fn fstrans_mount "struct mount *mp"
+.Ft void
+.Fn fstrans_unmount "struct mount *mp"
 .Ft void
 .Fn fstrans_start "struct mount *mp" "enum fstrans_lock_type lock_type"
 .Ft int
@@ -56,6 +56,10 @@
 .Ft void
 .Fn fstrans_done "struct mount *mp"
 .Ft int
+.Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state"
+.Ft "enum fstrans_state"
+.Fn fstrans_getstate "struct mount *mp"
+.Ft int
 .Fn fstrans_is_owner "struct mount *mp"
 .Ft int
 .Fn fscow_establish "struct mount *mp" \
@@ -68,105 +72,224 @@
 .Sh DESCRIPTION
 The
 .Nm
-subsystem is a set of operations to assist file system suspension.
-These operations must not be used outside of file systems.
+subsystem assists file system suspension and copy-on-write snapshots.
 .Pp
-File systems supporting this subsystem must set the flag
-.Dv IMNT_HAS_TRANS
-in
-.Dv "mnt_iflag" .
+For a file system to use
+.Nm ,
+its
+.Xr VFS_MOUNT 9
+method must call
+.Fn fstrans_mount ,
+and its
+.Xr VFS_UNMOUNT 9
+method must call
+.Fn fstrans_unmount .
+.Pp
+The file system's normal operations, such as its
+.Xr vnodeops 9 ,
+must be bracketed by
+.Fn fstrans_start
+and
+.Fn fstrans_done
+in a
+.Em shared
+transaction, which is blocked by suspending the file system and while
+it is suspended.
 .Pp
-File systems are always in one of these states:
+Operations needed to sync the file system to its backing store must be
+bracketed by
+.Fn fstrans_start
+and
+.Fn fstrans_done
+in a
+.Em lazy
+transaction, which is allowed while suspending the file system in order
+to sync it to its backing store, but blocked while the file system is
+suspended.
 .Pp
-.Bl -tag -offset indent -width FSTRANS_SUSPENDING -compact
-.It Dv FSTRANS_NORMAL
-Normal operations.
-.It Dv FSTRANS_SUSPENDING
-Preparing a suspension.
-.It Dv FSTRANS_SUSPENDED
-Suspended.
+Transactions are per-thread and nestable: if a thread is already in a
+transaction, it can enter another transaction.
+Each
+.Fn fstrans_start
+must be paired with
+.Fn fstrans_done .
+Entering a shared transaction while in a lazy transaction is not
+allowed and will lead to deadlock.
+.Pp
+The file system's
+.Xr VFS_SUSPENDCTL 9
+method can use
+.Fn fstrans_setstate
+to:
+.Bl -dash
+.It
+enter the
+.Dv FSTRANS_SUSPENDING
+to suspend all normal operations but allow syncing,
+.It
+enter the
+.Dv FSTRANS_SUSPENDED
+state to suspend all operations once synced, and
+.It
+restore to the
+.Dv FSTRANS_NORMAL
+state to resume all operations.
 .El
 .Pp
-This state is represented by
-.Vt "enum fstrans_state" .
-.Pp
-All file system operations use a
-.Em "fstrans lock" .
-This lock is recursive.
-A thread already owning a lock will always get another lock.
-The lock has two variants:
-.Bl -tag -offset indent -width FSTRANS_SHARED
-.It Dv FSTRANS_SHARED
-A lock that will be granted if the file system is in state
-.Dv FSTRANS_NORMAL .
-.It Dv FSTRANS_LAZY
-A lock that will be granted if the file system is in state
-.Dv FSTRANS_NORMAL
-or
-.Dv FSTRANS_SUSPENDING .
-It needs special care because operations using this variant will not block
-while the file system prepares suspension.
-.El
-.Pp
-The lock variant is represented by
-.Vt "enum fstrans_lock_type" .
+A file system supporting
+.Nm
+may establish a copy-on-write callback with
+.Fn fscow_establish .
+The copy-on-write callback will be called every time a buffer is
+written to a block device with
+.Fn VOP_STRATEGY
+and every time a buffer is read into the
+.Xr buffercache 9
+with
+.Dv B_MODIFY
+set indicating the caller's intent to modify it.
+Anyone modifying a buffer may additionally use
+.Fn fscow_run
+to explicitly invoke the established callback.
+The copy-on-write callback must be disestablished with
+.Fn fscow_disestablish
+when the file system is done with it.
 .Sh FUNCTIONS
-The following functions comprise the
-.Tn API
-provided by
-.Nm .
-.Bl -tag -width compact
-.It Fn fstrans_getstate "mp"
-Returns the current state of the file system
+.Bl -tag -width abcd
+.It Fn fstrans_mount "mp"
+Initialize the
+.Nm
+subsystem for the file system mounted at
 .Fa mp .
-.It Fn fstrans_setstate "mp" "new_state"
-Changes the state of the file system
-.Fa mp
-to
-.Fa new_state .
+Sets
+.Dv IMNT_HAS_TRANS
+in
+.Fa mp Ns Li "->mnt_iflag" .
+Return zero on success, or error code if
+.Xr vfs_busy 9
+fails.
+.It Fn fstrans_unmount "mp"
+Finalize the
+.Nm
+subsystem.
+Clears
+.Dv IMNT_HAS_TRANS
+in
+.Fa mp Ns Li "->mnt_iflag" .
+Caller is responsible for ensuring that no transactions are active.
 .It Fn fstrans_start "mp" "lock_type"
-Sets a lock of type
+Begin a transaction of type
 .Fa lock_type
 on the file system
-.Fa mp .
+.Fa mp
+in the current thread.
+If the file system is in a state that blocks such transactions, wait
+until it changes state to one that does not.
+.Bl -tag -width FSTRANS_SHARED
+.It Dv FSTRANS_SHARED
+If the file system is suspending or suspended, wait until it is
+resumed.
+Intended for normal file system operations.
+.It Dv FSTRANS_LAZY
+If the file system is suspended, wait until it is resumed.
+Intended for operations needed to sync the file system to its backing
+store in order to suspend it.
+.El
 .It Fn fstrans_start_nowait "mp" "lock_type"
 Like
 .Fn fstrans_start ,
-but will not wait for a state change of the file system when attempting to
-acquire the lock.
-The thread may still sleep while attempting to acquire the lock.
+but return
+.Dv EBUSY
+immediately if
+.Fa lock_type
+transactions are blocked in its current state.
+.Pp
+May sleep nevertheless on internal locks.
 .It Fn fstrans_done "mp"
-Releases a lock on the file system
+End the current transaction on
+.Fa mp .
+.It Fn fstrans_getstate "mp"
+Return the current state of the file system
 .Fa mp .
+.Pp
+Must be called within a transaction for the answer to be stable.
+.It Fn fstrans_setstate "mp" "new_state"
+Change the state of the file system
+.Fa mp
+to
+.Fa new_state ,
+and wait for all transactions not allowed in
+.Fa new_state
+to complete.
+.Bl -tag -width FSTRANS_SUSPENDING
+.It Dv FSTRANS_NORMAL
+Allow all transactions.
+.It Dv FSTRANS_SUSPENDING
+Block
+.Dv FSTRANS_SHARED
+transactions but allow
+.Dv FSTRANS_LAZY
+transactions.
+.It Dv FSTRANS_SUSPENDED
+Block all transactions.
+.El
+.Pp
+A thread that changes a file system to a state other than
+.Dv FSTRANS_NORMAL
+enters a transaction for the purposes of
+.Fn fstrans_getstate
+until it changes state back to
+.Dv FSTRANS_NORMAL .
+.Pp
+Additionally, a thread that changes a file system to a state other than
+.Dv FSTRANS_NORMAL
+acquires an exclusive lock on the file system state, so that
+.Fn fstrans_is_owner
+will return true in that thread, and no other thread can change the
+file system's state until the owner restores it to
+.Dv FSTRANS_NORMAL .
+.Pp
+May sleep, and may be interrupted by a signal.
+On success, return zero.
+On failure, restore the file system to the
+.Dv FSTRANS_NORMAL
+state and return an error code.
+.Fn fstrans_setstate
+never fails if
+.Fa new_state
+is
+.Dv FSTRANS_NORMAL .
 .It Fn fstrans_is_owner "mp"
-Returns
+Return
 .Dv true
-if this thread is currently suspending the file system
+if the current thread is currently suspending the file system
 .Fa mp .
 .It Fn fscow_establish "mp" "func" "cookie"
 Establish a copy-on-write callback for the file system
 .Fa mp .
 The function
 .Fa func