1.\" $NetBSD: fstrans.9,v 1.15 2010/04/12 21:28:55 jruoho Exp $ 2.\" 3.\" Copyright (c) 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Juergen Hannken-Illjes. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 13, 2010 31.Dt FSTRANS 9 32.Os 33.Sh NAME 34.Nm fstrans , 35.Nm fstrans_setstate , 36.Nm fstrans_getstate , 37.Nm fstrans_start , 38.Nm fstrans_start_nowait , 39.Nm fstrans_done , 40.Nm fstrans_is_owner , 41.Nm fscow_establish , 42.Nm fscow_disestablish , 43.Nm fscow_run 44.Nd file system suspension helper subsystem 45.Sh SYNOPSIS 46.In sys/mount.h 47.In sys/fstrans.h 48.Ft int 49.Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state" 50.Ft "enum fstrans_state" 51.Fn fstrans_getstate "struct mount *mp" 52.Ft void 53.Fn fstrans_start "struct mount *mp" "enum fstrans_lock_type lock_type" 54.Ft int 55.Fn fstrans_start_nowait "struct mount *mp" "enum fstrans_lock_type lock_type" 56.Ft void 57.Fn fstrans_done "struct mount *mp" 58.Ft int 59.Fn fstrans_is_owner "struct mount *mp" 60.Ft int 61.Fn fscow_establish "struct mount *mp" \ 62"int (*func)(void *, struct buf *, bool)" "void *cookie" 63.Ft int 64.Fn fscow_disestablish "struct mount *mp" \ 65"int (*func)(void *, struct buf *, bool)" "void *cookie" 66.Ft int 67.Fn fscow_run "struct buf *bp" "bool data_valid" 68.Sh DESCRIPTION 69The 70.Nm 71subsystem is a set of operations to assist file system suspension. 72These operations must not be used outside of file systems. 73.Pp 74File systems supporting this subsystem must set the flag 75.Dv IMNT_HAS_TRANS 76in 77.Dv "mnt_iflag" . 78.Pp 79File systems are always in one of these states: 80.Pp 81.Bl -tag -offset indent -width FSTRANS_SUSPENDING -compact 82.It Dv FSTRANS_NORMAL 83Normal operations. 84.It Dv FSTRANS_SUSPENDING 85Preparing a suspension. 86.It Dv FSTRANS_SUSPENDED 87Suspended. 88.El 89.Pp 90This state is represented by 91.Vt "enum fstrans_state" . 92.Pp 93All file system operations use a 94.Em "fstrans lock" . 95This lock is recursive. 96A thread already owning a lock will always get another lock. 97The lock has two variants: 98.Bl -tag -offset indent -width FSTRANS_SHARED 99.It Dv FSTRANS_SHARED 100A lock that will be granted if the file system is in state 101.Dv FSTRANS_NORMAL . 102.It Dv FSTRANS_LAZY 103A lock that will be granted if the file system is in state 104.Dv FSTRANS_NORMAL 105or 106.Dv FSTRANS_SUSPENDING . 107It needs special care because operations using this variant will not block 108while the file system prepares suspension. 109.El 110.Pp 111The lock variant is represented by 112.Vt "enum fstrans_lock_type" . 113.Sh FUNCTIONS 114The following functions comprise the 115.Tn API 116provided by 117.Nm . 118.Bl -tag -width compact 119.It Fn fstrans_getstate "mp" 120Returns the current state of the file system 121.Fa mp . 122.It Fn fstrans_setstate "mp" "new_state" 123Changes the state of the file system 124.Fa mp 125to 126.Fa new_state . 127.It Fn fstrans_start "mp" "lock_type" 128Sets a lock of type 129.Fa lock_type 130on the file system 131.Fa mp . 132.It Fn fstrans_start_nowait "mp" "lock_type" 133Like 134.Fn fstrans_start , 135but will not wait for a state change of the file system when attempting to 136acquire the lock. 137The thread may still sleep while attempting to acquire the lock. 138.It Fn fstrans_done "mp" 139Releases a lock on the file system 140.Fa mp . 141.It Fn fstrans_is_owner "mp" 142Returns 143.Dv true 144if this thread is currently suspending the file system 145.Fa mp . 146.It Fn fscow_establish "mp" "func" "cookie" 147Establish a copy-on-write callback for the file system 148.Fa mp . 149The function 150.Fa func 151will be called for every buffer written through this file system. 152.It Fn fscow_disestablish "mp" "func" "cookie" 153Disestablish a copy-on-write callback registered with 154.Fn fscow_establish . 155.It Fn fscow_run "bp" "data_valid" 156Run all copy-on-write callbacks established for the file system this buffer 157belongs to. 158If 159.Fa data_valid 160is 161.Dv true 162the buffer data has not yet been modified. 163.El 164.Sh RETURN VALUES 165The functions 166.Fn fstrans_setstate 167and 168.Fn fstrans_start_nowait 169return zero on success and an error value on failure. 170.Sh EXAMPLES 171The following is an example of a file system suspend operation. 172.Bd -literal 173int 174xxx_suspendctl(struct mount *mp, int cmd) 175{ 176 int error; 177 178 switch (cmd) { 179 case SUSPEND_SUSPEND: 180 error = fstrans_setstate(mp, FSTRANS_SUSPENDING); 181 if (error != 0) 182 return error; 183 184 /* Sync file system state to disk. */ 185 186 return fstrans_setstate(mp, FSTRANS_SUSPENDED); 187 188 case SUSPEND_RESUME: 189 return fstrans_setstate(mp, FSTRANS_NORMAL); 190 191 default: 192 return EINVAL; 193 } 194} 195.Ed 196.Pp 197This is an example of a file system operation. 198.Bd -literal 199int 200xxx_create(void *v) 201{ 202 struct vop_create_args *ap = v; 203 struct mount *mp = ap-\*[Gt]a_dvp-\*[Gt]v_mount; 204 int error; 205 206 if ((error = fstrans_start(mp, FSTRANS_SHARED)) != 0) 207 return error; 208 209 /* Actually create the node. */ 210 211 fstrans_done(mp); 212 213 return 0; 214} 215.Ed 216.Sh SEE ALSO 217.Xr vfs_resume 9 , 218.Xr vfs_suspend 9 219.Sh CODE REFERENCES 220The actual code implementing this subsystem can be found in the file 221.Pa sys/kern/vfs_trans.c . 222.Sh HISTORY 223The 224.Nm 225subsystem appeared in 226.Nx 5.0 . 227.Sh AUTHORS 228The 229.Nm 230subsystem was written by 231.An J\(:urgen Hannken-Illjes 232.Aq hannken@NetBSD.org . 233