Index: gvirstor.8
===================================================================
--- gvirstor.8	(revision 186226)
+++ gvirstor.8	(working copy)
@@ -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
@@ -72,7 +71,10 @@
 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.
+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 (free file system space).
 The first argument to
 .Nm
 indicates an action to be performed:
@@ -97,7 +99,8 @@
 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).
+module loaded, device present in /dev). This action can be safely perfomed
+while the virstor device is in use ("hot" operation).
 .It Cm remove
 Removes components from existing virtual device by its
 .Ar name .
@@ -143,7 +146,7 @@
 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
 .Ed
@@ -222,6 +225,29 @@
 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.
+.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 (like UFS/UFS2 does), their efforts will be effectively foiled by
+sequential allocation of chunks in
+.Nm
+and all their structures will be
+allocated at the start of the first virstor component. 
+This could have a significant impact on file system performance (which can
+in some cases be even positive).
 .Sh AUTHOR
 .An Ivan Voras Aq ivoras@FreeBSD.org 
 Sponsored by Google Summer of Code 2006