Several significant updates:

* Better wording of sections dealing with physical storage
* A new section on assumptions gvirstor has on its consumer devices
  (components) and its interaction  with file systems
* Improved markup (by hrs@)

Reviewed by:	hrs
Approved by:	gnn (mentor)

1 files changed, 105 insertions, 49 deletions

diff --git a/sbin/geom/class/virstor/gvirstor.8 b/sbin/geom/class/virstor/gvirstor.8
index 5807af9..4b11209 100644
--- a/sbin/geom/class/virstor/gvirstor.8
+++ b/sbin/geom/class/virstor/gvirstor.8
@@ -1,5 +1,4 @@
-.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
-.\" Copyright (c) 2005 Ivan Voras <ivoras@FreeBSD.org>
+.\" Copyright (c) 2006-2008 Ivan Voras <ivoras@FreeBSD.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -25,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 8, 2006
+.Dd December 17, 2008
 .Dt GVIRSTOR 8
 .Os
 .Sh NAME
@@ -69,10 +68,17 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility is used for setting up a storage device of arbitrary large size (for example,
-several TB), consisting of an arbitrary number of physical storage devices with
-total size <= the virtual size. Data for the virtual devices will be allocated from
-physical devices on demand. In short, this is the virtual storage functionality.
+utility is used for setting up a virtual storage device of arbitrary
+large size
+.Pq for example, several TB ,
+consisting of an arbitrary number of physical storage devices with the
+total size which is equal to or smaller than the virtual size.  Data
+for the virtual devices will be allocated from physical devices on
+demand. The idea behind
+.Nm
+is similar to the concept of Virtual Memory in operating systems,
+effectively allowing users to overcommit on storage
+.Pq free file system space .
 The first argument to
 .Nm
 indicates an action to be performed:
@@ -82,12 +88,15 @@ Set up a virtual device from the given components with the specified
 .Ar name .
 Metadata are stored in the last sector of every component.
 Argument
-.Ar virsize
-is the size of new virtual device, with default being 2 TiB (2097152 MiB).
+.Fl s Ar virsize
+is the size of new virtual device, with default being 2 TiB
+.Pq 2097152 MiB .
 Argument
-.Ar chunksize
-is the chunk size, with default being 4 MiB (4096 KiB).
-The default is thus "-s 2097152 -m 4096".
+.Fl m Ar chunksize
+is the chunk size, with default being 4 MiB
+.Pq 4096 KiB .
+The default is thus
+.Qq Fl s Ar 2097152 Fl m Ar 4096 .
 .It Cm stop
 Turn off an existing virtual device by its
 .Ar name .
@@ -96,8 +105,10 @@ As with other GEOM classes, stopped geoms cannot be started manually.
 .It Cm add
 Adds new components to existing virtual device by its
 .Ar name .
-The specified virstor device must exist and be active (i.e.
-module loaded, device present in /dev).
+The specified virstor device must exist and be active
+.Pq i.e. module loaded, device present in Pa /dev .
+This action can be safely performed while the virstor device is in use
+.Pq Qo hot Qc operation
 .It Cm remove
 Removes components from existing virtual device by its
 .Ar name .
@@ -130,82 +141,97 @@ Hardcode providers' names in metadata.
 Be more verbose.
 .El
 .Sh EXIT STATUS
-Exit status is 0 on success, and 1 if the command fails.
+The
+.Nm
+utility exits 0 on success, and 1 if an error occurs.
 .Sh EXAMPLES
 The following example shows how to create a virtual device of default size
-(2 TiB), of default chunk (extent) size (4 MiB), with two physical devices for
-backing storage.
+.Pq 2 TiB ,
+of default chunk
+.Pq extent
+size
+.Pq 4 MiB ,
+with two physical devices for backing storage.
 .Bd -literal -offset indent
-gvirstor label -v mydata /dev/ad4 /dev/ad6
-newfs /dev/virstor/mydata
+.No gvirstor label -v Ar mydata Ar /dev/ad4 Ar /dev/ad6
+.No newfs Ar /dev/virstor/mydata
 .Ed
 .Pp
 From now on, the virtual device will be available via the
 .Pa /dev/virstor/mydata
 device entry.
-To add a new physical device / provider to an active virstor device:
+To add a new physical device / component to an active virstor device:
 .Bd -literal -offset indent
-gvirstor add mydata ad8
+.No gvirstor add Ar mydata Ar ad8
 .Ed
 .Pp
-This will add physical storage (from ad8) to 
+This will add physical storage
+.Ar ad8
+to
 .Pa /dev/virstor/mydata
 device.
-To see device status information (including how much physical storage 
-is still available for the virtual device), use:
+To see device status information
+.Pq including how much physical storage is still available for the virtual device ,
+use:
 .Bd -literal -offset indent
 gvirstor list
 .Ed
 .Pp
 All standard
 .Xr geom 8
-subcommands (e.g. "status", "help") are also supported.
-.Sh SYSCTLs
+subcommands
+.Pq e.g. Cm status , Cm help
+are also supported.
+.Sh SYSCTL VARIABLES
 .Nm
-has several 
+has several
 .Xr sysctl 8
 tunable variables.
 .Bd -literal -offset indent
-.Pa int kern.geom.virstor.debug
+.Va int kern.geom.virstor.debug
 .Ed
 .Pp
 This sysctl controls verbosity of the kernel module, in the range
-1 to 15. Messages that are marked with higher verbosity levels than 
-this are supressed. Default value is 5 and it's not
-recommented to set this tunable to less than 2, because level 1 messages 
+1 to 15. Messages that are marked with higher verbosity levels than
+this are suppressed. Default value is 5 and it's not
+recommended to set this tunable to less than 2, because level 1 messages
 are error events, and level 2 messages are system warnings.
 .Bd -literal -offset indent
-.Pa int kern.geom.virstor.chunk_watermark
+.Va int kern.geom.virstor.chunk_watermark
 .Ed
 .Pp
 Value in this sysctl sets warning watermark level for physical chunk usage
 on a single component. The warning is issued when a virstor component
-has less than this many free chunks (default 100).
+has less than this many free chunks
+.Pq default 100 .
 .Bd -literal -offset indent
-.Pa int kern.geom.virstor.component_watermark
+.Va int kern.geom.virstor.component_watermark
 .Ed
 .Pp
 Value in this sysctl sets warning watermark level for component usage.
-The warning is issed when there are less than this many unallocated
-components (default is 1).
+The warning is issued when there are less than this many unallocated
+components
+.Pq default is 1 .
 .Pp
 All these sysctls are also available as
 .Xr loader 8
 tunables.
-.Sh LOG MESSAGES
+.Sh DIAGNOSTICS
 .Nm
-kernel module issues log messages with prefixes in standardised format,
+kernel module issues log messages with prefixes in standardized format,
 which is useful for log message filtering and dispatching. Each message
 line begins with
 .Bd -literal -offset indent
-.Pa GEOM_VIRSTOR[%d]: 
+.Li GEOM_VIRSTOR[%d]:
 .Ed
 .Pp
-The number (%d) is message verbosity / importance level, in the range
-1 to 15. If a message filtering, dispatching or operator alert system is
-used, it is recommended that messages with levels 1 and 2 be taken
-seriously (for example, to catch out-of-space conditions as set by
-watermark sysctls).
+The number
+.Pq %d
+is message verbosity / importance level, in the range 1 to 15. If a
+message filtering, dispatching or operator alert system is used, it is
+recommended that messages with levels 1 and 2 be taken seriously
+.Pq for example, to catch out-of-space conditions as set by watermark
+sysctls .
 .Sh SEE ALSO
 .Xr geom 4 ,
 .Xr geom 8 ,
@@ -218,10 +244,40 @@ The
 utility appeared in
 .Fx 7.0 .
 .Sh BUGS
-Commands "add" and "remove" contain unavoidable critical sections
-which may make the virstor device unusable if a power failure (or
-other disruptive event) happens during their execution. 
-It's recommended to run them when the system is quiescent.
+Commands
+.Cm add
+and
+.Cm remove
+contain unavoidable critical sections which may make the virstor
+device unusable if a power failure
+.Pq or other disruptive event
+happens during their execution.  It's recommended to run them when the
+system is quiescent.
+.Sh ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS
+There are several assumptions that
+.Nm
+has in its operation: that the size of the virtual storage device will not
+change once it's set, and that the sizes of individual physical storage
+components will always remain constant during their existence. For
+alternative ways to implement virtual or resizable file systems see
+.Xr zfs 1M ,
+.Xr gconcat 8 and
+.Xr growfs 8 .
+.Pp
+Note that
+.Nm
+has nontrivial interaction with file systems which initialize a large
+number of on-disk structures during newfs.  If such file systems
+attempt to spread their structures across the drive media
+.Pq like UFS/UFS2 does ,
+their efforts will be effectively foiled by sequential allocation of
+chunks in
+.Nm
+and all their structures will be physically allocated at the start
+of the first virstor component.  This could have a significant impac
+t on file system performance
+.Pq which can in some rare cases be even positive .
 .Sh AUTHOR
-.An Ivan Voras Aq ivoras@FreeBSD.org 
+.An Ivan Voras Aq ivoras@FreeBSD.org
+.Pp
 Sponsored by Google Summer of Code 2006