[PATCH] md: Allow md to select between superblock formats

The code to understand a specific superblock format is
already highly localised in md.  This patch defines a
user-space interface for selecting which superblock format
to use, and obeys that selection.

Md currently has a concept of 3 version numbers:
 A major version number
 A minor version number
 A patch version number

There historically seems to be some confusion about whether
these refer to a version of the superblock layout,
or a version of the software.

We will now define that:
   the "major_version" defines the superblock handler.
      '0' is the current superblock format.  All new formats
          will need new numbers.
   the "minor_version" can specify minor variations in the
      superblock, such as different location on the device
   the "patch_version" will be used to indicate new extenstions
      to the software.. patch_version=1 will mean multiple superblock
      support.

A superblock version number is selected by specifing major_version
in SET_ARRAY_INFO ioctl.

This patch:
  Updates Documentation/md.txt with details of new interface.
  Generalises desc_nr handling and makes sure that an array never
  has two devices with the same desc_nr.
  makes sure mddev->major_version is always valid and is 0 by default.
  uses mddev->major_version to select superblock handlers.
  Modifies set_array_info to just record version number if raid_disks==0
  Makes sure max_disks is always set correctly.
  Determines device size when reading superblock, or a hot-add/add-new.

Documentation/md.txt

 Tools that manage md devices can be found at
-   http://www.<country>.kernel.org/pub/linux/daemons/raid/....
+   http://www.<country>.kernel.org/pub/linux/utils/raid/....
 
 
 
-You can boot (if you selected boot support in the configuration) with your md 
-device with the following kernel command lines:
+You can boot with your md device with the following kernel command
+lines:
 
 for old raid arrays without persistent superblocks:
   md=<md device no.>,<raid level>,<chunk size factor>,<fault level>,dev0,dev1,...,devn
@@ -33,4 +33,64 @@ dev0-devn: e.g. /dev/hda1,/dev/hdc1,/dev/sda1,/dev/sdb1
 A possible loadlin line (Harald Hoyer <HarryH@Royal.Net>)  looks like this:
 
 e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro
-			    
+
+-------------------------------
+The md driver can support a variety of different superblock formats.
+(It doesn't yet, but it can)
+
+The kernel does *NOT* autodetect which format superblock is being
+used. It must be told.
+
+Superblock format '0' is treated differently to others for legacy
+reasons.
+
+
+General Rules - apply for all superblock formats
+------------------------------------------------
+
+An array is 'created' by writing appropriate superblocks to all
+devices.
+It is 'assembled' by associating each of these devices with an
+particular md virtual device.  Once it is completely assembled, it can
+be accessed.
+
+An array should be created by a user-space tool.  This will write
+superblocks to all devices.  It will usually mark the array as
+'unclean', or with some devices missing so that the kernel md driver
+can create approrpriate redundancy (copying in raid1, parity
+calculation in raid4/5).
+
+When an array is assembled, it is first initialised with the
+SET_ARRAY_INFO ioctl.  This contains, in particular, a major and minor
+version number.  The major version number selects which superblock
+format is to be used.  The minor number might be used to tune handling
+of the format, such as suggesting where on each device to look for the
+superblock.
+
+Then each device is added using the ADD_NEW_DISK ioctl.  This
+provides, in particular, a major and minor number identifying the
+device to add.
+
+The array is started with the RUN_ARRAY ioctl.
+
+Once started, new devices can be added.  They should have an
+appropriate superblock written to them, and then passed be in with
+ADD_NEW_DISK.
+
+Devices that have failed or are not yet active can be detached from an
+array using HOT_REMOVE_DISK.
+
+
+Specific Rules that apply to format-0 super block arrays, and
+       arrays with no superblock (non-presistant).
+-------------------------------------------------------------
+
+An array can be 'created' by describing the array (level, chunksize
+etc) in a SET_ARRAY_INFO ioctl.  This must has major_version==0 and
+raid_disks != 0.
+Then uninitialised devices can be added with ADD_NEW_DISK.  The
+structure passed to ADD_NEW_DISK must specify the state of the device
+and it's role in the array.
+
+One started with RUN_ARRAY, uninitialised spares can be added with
+HOT_ADD_DISK.