From bc6528ab7ab2e9292c9d3db3eba1f10cbe11494c Mon Sep 17 00:00:00 2001 From: simonb Date: Thu, 31 Jul 2008 08:28:17 +0000 Subject: [PATCH] Add Greg Oster's man page for WAPBL. Still a work in progress, expect updates. Thanks a lot to Greg for cribbing together the info and getting this going. --- distrib/sets/lists/man/mi | 4 +- share/man/man4/Makefile | 6 +- share/man/man4/wapbl.4 | 187 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 193 insertions(+), 4 deletions(-) create mode 100644 share/man/man4/wapbl.4 diff --git a/distrib/sets/lists/man/mi b/distrib/sets/lists/man/mi index c331c1f180c0..4d8b2395631b 100644 --- a/distrib/sets/lists/man/mi +++ b/distrib/sets/lists/man/mi @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.1081 2008/07/22 21:08:00 dyoung Exp $ +# $NetBSD: mi,v 1.1082 2008/07/31 08:28:17 simonb Exp $ # # Note: don't delete entries from here - mark them as "obsolete" instead. # @@ -1616,6 +1616,7 @@ ./usr/share/man/cat4/vmnet.0 man-sys-catman .cat ./usr/share/man/cat4/vnd.0 man-sys-catman .cat ./usr/share/man/cat4/vr.0 man-sys-catman .cat +./usr/share/man/cat4/wapbl.0 man-sys-catman .cat ./usr/share/man/cat4/wd.0 man-sys-catman .cat ./usr/share/man/cat4/wdc.0 man-sys-catman .cat ./usr/share/man/cat4/wds.0 man-sys-catman .cat @@ -4189,6 +4190,7 @@ ./usr/share/man/man4/vmnet.4 man-sys-man .man ./usr/share/man/man4/vnd.4 man-sys-man .man ./usr/share/man/man4/vr.4 man-sys-man .man +./usr/share/man/man4/wapbl.4 man-sys-man .man ./usr/share/man/man4/wd.4 man-sys-man .man ./usr/share/man/man4/wdc.4 man-sys-man .man ./usr/share/man/man4/wds.4 man-sys-man .man diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index f2fbeb7935b9..78a9efdfc57a 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.468 2008/07/31 08:01:59 simonb Exp $ +# $NetBSD: Makefile,v 1.469 2008/07/31 08:28:17 simonb Exp $ # @(#)Makefile 8.1 (Berkeley) 6/18/93 MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 acpidalb.4 \ @@ -54,8 +54,8 @@ MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 acpidalb.4 \ tp.4 tr.4 tra.4 trm.4 tty.4 tun.4 tqphy.4 twa.4 twe.4 txp.4 \ ubsec.4 udp.4 uep.4 ug.4 uha.4 uk.4 ukphy.4 unix.4 userconf.4 \ veriexec.4 vga.4 vge.4 viaide.4 vlan.4 vmmon.4 vmnet.4 vnd.4 vr.4 \ - wd.4 wdc.4 wi.4 wm.4 wpi.4 wscons.4 wsdisplay.4 wsfont.4 wskbd.4 \ - wsmouse.4 wsmux.4 \ + wapbl.4 wd.4 wdc.4 wi.4 wm.4 wpi.4 wscons.4 wsdisplay.4 wsfont.4 \ + wskbd.4 wsmouse.4 wsmux.4 \ xbox.4 xge.4 \ yds.4 ym.4 \ zero.4 zstty.4 zyd.4 diff --git a/share/man/man4/wapbl.4 b/share/man/man4/wapbl.4 new file mode 100644 index 000000000000..35e4535fc3e7 --- /dev/null +++ b/share/man/man4/wapbl.4 @@ -0,0 +1,187 @@ +.\" $NetBSD: wapbl.4,v 1.1 2008/07/31 08:28:17 simonb Exp $ +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" 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 July 21, 2008 +.Dt WAPBL 4 +.Os +.Sh NAME +.Nm WAPBL +.Nd Write Ahead Physical Block Logging file system journalling +.Sh SYNOPSIS +.Cd options WAPBL +.Cd options WAPBL_DEBUG +.Cd options WAPBL_DEBUG_SERIALIZE +.Sh DESCRIPTION +The +.Nm +driver provides meta-data journalling for file systems. In +particular, it is used with the fast file system (FFS) to provide +rapid file system consistency checking after a system outage. +It also provides better general-use performance over regular FFS. +.Pp +WAPBL currently maintains its journal in one of two locations: +.Bl -tag -width indent +.It - After the file system +The journal is placed in the same partition as the file system, but +between the filesystem and the end of the partition. +.It - Within the file system +The journal is allocated as a special contiguous file within the +filesystem. +The journal file is not visible via normal file system access. +.El +.Pp +A new journal is created automatically when a file system is mounted +via +.Xr mount 8 +with the +.Pa -o log +option. +If no journal size has been specified with +.Xr tunefs 8 , +then the size of the journal +will be based on 1MB of journal per 1GB of file system, to a maximum +journal size of 64MB. +.Pp +If there is adequate space between the end of the the file system and +the end of the partition, then unless the journal size has been +specified with +.Xr tunefs 8 +then the journal will be created after the file system. +To obtain space between the file system and the end of the partition +the size of the partition can be adjusted using +.Xr disklabel 8 . +Care must be taken not to damage existing data on existing partitions, +but this method will work well if, for example, a swap partition can +be shrunk in order to accommodate the journal after the file system on +a partition before the swap partition. +.Pp +For a new file system, +.Bd -literal -offset indent +newfs -s -64m /dev/rwd0a +.Ed +.Pp +can be used to leave space for a 64MB journal at the end of +.Pa /dev/rwd0a . +.Pp +To specify the size of the journal within the file system +.Xr tunefs 8 +can be used as follows: +.Bd -literal -offset indent +tunefs -l 64m /dev/rwd0a +.Ed +.Pp +to indicate that a journal of size 64MB on the file system on +.Pa /dev/rwd0a +should be created the next time that file system is mounted. +This must be done before the file system is mounted with the +.Dq -o log +option. +For existing file systems and general use, however, simply using +.Bd -literal -offset indent +mount -o log /dev/rwd0a /mnt +.Ed +.Pp +will be sufficient to create an appropriate journal within the file +system. +Running +.Bd -literal -offset indent +tunefs -l 0 /dev/rwd0a +.Ed +.Pp +will schedule the log for removal on the next read-write mount, and +running +.Bd -literal -offset indent +tunefs -l 0 /dev/rwd0a +.Ed +.Pp +followed by +.Bd -literal -offset indent +mount -o log /dev/rwd0a /mnt +.Ed +.Pp +will remove the log and then re-create it with the default size. +This method can also be used to grow or shrink the size of the journal. +.Pp +With the journal, +.Xr fsck 8 +is no longer required at system boot. +If the system has been shutdown in an unclean fashion then the journal +will be replayed when the file system is mounted. +.Xr fsck 8 +can still be used to force a consistency check of the file system +should that be desired. +.Xr WAPBL 8 +has a number of debugging options. +The option +.Bd -unfilled -offset indent +options WAPBL_DEBUG +.Ed +.Pp +turns on general debugging. +The option +.Bd -unfilled -offset indent +options WAPBL_DEBUG_SERIALIZE +.Ed +.Pp +forces the serialization of all IO. +This is currently be used to help alleviate a performance issue +seen on multi-core machines, where multiple simultaneous extractions +of tar-files can cause degenerate performance. +.Pp +.Sh SEE ALSO +.Xr config 1 , +.Xr fsck 8 , +.Xr newfs 8 , +.Xr mount 8 , +.Xr umount 8 +.Sh CAVEATS +.Xr fsync 2 +causes the journal to be committed to disk, resulting in +non-negligible performance issues. +.Pp +There are also some pending issues with multiple simultaneous tar-file +extractions resulting in degenerate file system behavior. +The current work-around is to use +.Bd -unfilled -offset indent +options WAPBL_DEBUG_SERIALIZE +.Ed +.Pp +as mentioned above. +.Pp +In-file system log allocation should be done on a relatively quiet +file system. The error path for the log allocation could result in a +.Dq dangling inode +issue. +.Pp +If the file system is full then making a journal can fail. +.Sh HISTORY +.Nm +was originally written by Darrin B. Jewell while at Wasabi Systems +Inc. +Wasabi Systems contributed the code to +.Nx +and it first appeared in +.Nx 5.0 .