.\"     $NetBSD: fstrans.9,v 1.12 2008/04/30 13:10:58 martin Exp $
.\"
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Juergen Hannken-Illjes.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 2, 2007
.Dt FSTRANS 9
.Os
.Sh NAME
.Nm fstrans ,
.Nm fstrans_setstate ,
.Nm fstrans_getstate ,
.Nm fstrans_start ,
.Nm fstrans_start_nowait ,
.Nm fstrans_done ,
.Nm fstrans_is_owner ,
.Nm fscow_establish ,
.Nm fscow_disestablish ,
.Nm fscow_run
.Nd file system suspension helper subsystem
.Sh SYNOPSIS
.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"
.Ft void
.Fn fstrans_start "struct mount *mp" "enum fstrans_lock_type lock_type"
.Ft int
.Fn fstrans_start_nowait "struct mount *mp" "enum fstrans_lock_type lock_type"
.Ft void
.Fn fstrans_done "struct mount *mp"
.Ft int
.Fn fstrans_is_owner "struct mount *mp"
.Ft int
.Fn fscow_establish "struct mount *mp" \
"int (*func)(void *, struct buf *, bool)" "void *cookie"
.Ft int
.Fn fscow_disestablish "struct mount *mp" \
"int (*func)(void *, struct buf *, bool)" "void *cookie"
.Ft int
.Fn fscow_run "struct buf *bp" "bool data_valid"
.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.
.Pp
File systems supporting this subsystem must set the flag
.Dv IMNT_HAS_TRANS
in
.Dv "mnt_iflag" .
.Pp
File systems are always in one of these states:
.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.
.El
This state is represented by
.Vt "enum fstrans_state" .
.Bl -tag -width compact
.It Fn fstrans_getstate "mp"
returns the current state of the file system
.Fa mp .
.Pp
.It Fn fstrans_setstate "mp" "new_state"
changes the state of the file system
.Fa mp
to
.Fa new_state .
.El
.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 -compact
.It Dv FSTRANS_SHARED
this lock will be granted if the file system is in state
.Dv FSTRANS_NORMAL .
.It Dv FSTRANS_LAZY
this lock 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
The lock variant is represented by
.Vt "enum fstrans_lock_type" .
.Bl -tag -width compact
.It Fn fstrans_start "mp" "lock_type"
sets a lock of type
.Fa lock_type
on the file system
.Fa mp .
.It Fn fstrans_start_nowait "mp" "lock_type"
will not wait for a state change of the file system when attempting to
aquire the lock.
The thread may still sleep while attempting to aquire the lock.
.It Fn fstrans_done "mp"
releases a lock on the file system
.Fa mp .
.It Fn fstrans_is_owner "mp"
returns
.Dv true
if this 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 .
.Fa func
will be called for every buffer written through this file system.
.It Fn fscow_disestablish "mp" "func" "cookie"
Disestablish a copy-on-write callback registered with
.Fn fscow_establish .
.It Fn fscow_run "bp" "data_valid"
Run all copy-on-write callbacks established for the file system this buffer
belongs to.
If
.Fa data_valid
is
.Dv true
the buffer data has not yet been modified.
.El
.Sh RETURN VALUES
The functions
.Fn fstrans_setstate
and
.Fn fstrans_start_nowait
return zero on success and an error value on failure.
.Sh EXAMPLES
The following is an example of a file system suspend operation.
.Bd -literal
int
xxx_suspendctl(struct mount *mp, int cmd)
{
	int error;

	switch (cmd) {
	case SUSPEND_SUSPEND:
		error = fstrans_setstate(mp, FSTRANS_SUSPENDING);
		if (error != 0)
			return error;

		/* Sync file system state to disk. */

		return fstrans_setstate(mp, FSTRANS_SUSPENDED);

	case SUSPEND_RESUME:
		return fstrans_setstate(mp, FSTRANS_NORMAL);

	default:
		return EINVAL;
	}
}
.Ed
.Pp
This is an example of a file system operation.
.Bd -literal
int
xxx_create(void *v)
{
	struct vop_create_args *ap = v;
	struct mount *mp = ap-\*[Gt]a_dvp-\*[Gt]v_mount;
	int error;

	if ((error = fstrans_start(mp, FSTRANS_SHARED)) != 0)
		return error;

	/* Actually create the node. */

	fstrans_done(mp);

	return 0;
}
.Ed
.Sh SEE ALSO
.Xr vfs_resume 9 ,
.Xr vfs_suspend 9
.Sh CODE REFERENCES
The actual code implementing this subsystem can be found in the file
.Pa sys/kern/vfs_trans.c .
.Sh HISTORY
The
.Nm
subsystem appeared in
.Nx 5.0 .
.Sh AUTHORS
The
.Nm
subsystem was written by
.if t .An J\(:urgen Hannken-Illjes
.if n .An Juergen Hannken-Illjes
.Aq hannken@NetBSD.org .