Bring ccd documentation up to date. Reference vinum, elucidate more

    on mirroring and interleaving.

1 files changed, 47 insertions, 4 deletions

diff --git a/share/man/man4/ccd.4 b/share/man/man4/ccd.4
index 0bdc790..169a41d 100644
--- a/share/man/man4/ccd.4
+++ b/share/man/man4/ccd.4
@@ -72,12 +72,17 @@ The count argument is how many
 .Nm ccds
 memory is allocated for a boot time.  In this example, no more than 4
 .Nm ccds
-may be configured.
+may be configured.  As of the FreeBSD 3.0 release, you do not need to
+configure your kernel with ccd but may instead use it as a kernel loadable
+module.  Simply running
+.Nm ccdconfig 
+will load the module into the kernel.
 .Pp
 A
 .Nm ccd
 may be either serially concatenated or interleaved.  To serially
 concatenate the partitions, specify the interleave factor of 0.
+Note that mirroring may not be used with an interleave factor of 0.
 .Pp
 There is a run-time utility that is used for configuring
 .Nm ccds .
@@ -96,7 +101,18 @@ is typically the size of a track, while for large reads, it is about a
 quarter of a track. (Note that this changes greatly depending on the
 number and speed of disks.)  For instance, with eight 7,200 RPM drives
 on two Fast-Wide SCSI buses, this translates to about 128 for writes
-and 32 for reads.
+and 32 for reads.  A larger interleave tends to work better when the
+disk is taking a multitasking load by localizing the file I/O from
+any given process onto a single disk.  You lose sequential performance when
+you do this, but sequential performance is not usually an issue with a 
+multitasking load.
+.Pp
+An interleave factor must be specified when using a mirroring configuration,
+even when you have only two disks (i.e. the layout winds up being the same
+no matter what the interleave factor).  The interleave factor will determine
+how I/O is broken up, however, and a value 128 or greater is recommended.
+.Pp
+CCD has an option for a parity disk, but does not currently implement it.
 .Pp
 The best performance is achieved if all component disks have the same
 geometry and size.  Optimum striping cannot occur with different
@@ -116,7 +132,18 @@ to
 .Dq mirror
 any even number of disks.  See
 .Xr ccdconfig 8
-for how to specify the necessary flags.  In an event of a disk
+for how to specify the necessary flags.   For example, if you have a ccd
+configuration specifying four disks, the first two disks will be mirrored with
+the second two disks.  A write will be run to both sides of
+the mirror.  A read will be run to either side of the mirror depending
+on what the driver believes to be most optimal.  If the read fails,
+the driver will automatically attempt to read the same sector from the
+other side of the mirror.  Currently
+.Nm ccd
+uses a duel seek zone model to optimize reads for a multi-tasking load
+rather then a sequential load.
+.Pp
+In an event of a disk
 failure, you can use
 .Xr dd 1
 to recover the failed disk.
@@ -129,11 +156,26 @@ if you have a filesystem on a two-disk mirrored
 and one of the disks fail, you cannot mount and use the remaining
 partition as itself; you have to configure it as a one-disk
 .Nm ccd.
+You cannot replace a disk in a mirrored
+.Nm ccd
+partition without first backing up the partition, then replacing the disk,
+then restoring the partition.
 .Sh WARNINGS
 If just one (or more) of the disks in a
 .Nm ccd
 fails, the entire
 file system will be lost unless you are mirroring the disks.
+.Pp
+If one of the disks in a mirror is lost, you should still
+be able to backup your data.  If a write error occurs, however, data
+read from that sector may be non-deterministic.  It may return the data
+prior to the write or it may return the data that was written.  When a 
+write error occurs, you should recover and regenerate the data as soon
+as possible.
+.Pp
+Changing the interleave or other parameters for a 
+.Nm ccd
+disk usually destroys whatever data previously existed on that disk.
 .Sh FILES
 /dev/{,r}ccd* - ccd device special files.
 .Pp
@@ -148,4 +190,5 @@ Utah.
 .Xr fsck 8 ,
 .Xr MAKEDEV 8 ,
 .Xr mount 8 ,
-.Xr newfs 8 .
+.Xr newfs 8 ,
+.Xr vinum 8 .