Add some comments to explain some of the bits of superswitch.

diff --git a/mdadm.h b/mdadm.h
index 9d4f6b78b225251f6f6c936fd52f67c2573a0f34..97569fad0711dd5d5fddbf1fb3ccd5b7c841f072 100644 (file)
--- a/mdadm.h
+++ b/mdadm.h
@@ -374,27 +374,120 @@ extern char *map_dev(int major, int minor, int create);
 struct active_array;
 struct metadata_update;
 
+/* A superswitch provides entry point the a metadata handler.
+ *
+ * The super_switch primarily operates on some "metadata" that
+ * is accessed via the 'supertype'.
+ * This metadata has one of three possible sources.
+ * 1/ It is read from a single device.  In this case it may not completely
+ *    describe the array or arrays as some information might be on other
+ *    devices.
+ * 2/ It is read from all devices in a container.  In this case all
+ *    information is present.
+ * 3/ It is created by ->init_super / ->add_to_super.  In this case it will
+ *    be complete once enough ->add_to_super calls have completed.
+ *
+ * When creating an array inside a container, the metadata will be
+ * formed by a combination of 2 and 3.  The metadata or the array is read,
+ * then new information is added.
+ *
+ * The metadata must sometimes have a concept of a 'current' array
+ * and a 'current' device.
+ * The 'current' array is set by init_super to be the newly created array,
+ * or is set by super_by_fd when it finds it is looking at an array inside
+ * a container.
+ *
+ * The 'current' device is either the device that the metadata was read from
+ * in case 1, or the last device added by add_to_super in case 3.
+ * Case 2 does not identify a 'current' device.
+ */
 extern struct superswitch {
+
+       /* Used to report details of metadata read from a component
+        * device. ->load_super has been called.
+        */
        void (*examine_super)(struct supertype *st, char *homehost);
        void (*brief_examine_super)(struct supertype *st);
        void (*export_examine_super)(struct supertype *st);
+
+       /* Used to report details of an active array.
+        * ->load_super was possibly given a 'component' string.
+        */
        void (*detail_super)(struct supertype *st, char *homehost);
        void (*brief_detail_super)(struct supertype *st);
        void (*export_detail_super)(struct supertype *st);
+
+       /* Used:
+        *   to get uuid to storing in bitmap metadata
+        *   and 'reshape' backup-data metadata
+        *   To see if a device is being re-added to an array it was part of.
+        */
        void (*uuid_from_super)(struct supertype *st, int uuid[4]);
+
+       /* Extra generic details from metadata.  This could be details about
+        * the container, or about an individual array within the container.
+        * The determination is made either by:
+        *   load_super being given a 'component' string.
+        *   validate_geometry determining what to create.
+        * getinfo_super_n really needs to be removed..
+        */
        void (*getinfo_super)(struct supertype *st, struct mdinfo *info);
        void (*getinfo_super_n)(struct supertype *st, struct mdinfo *info);
+
+       /* Check if the given metadata is flagged as belonging to "this"
+        * host.  For arrays that don't determine a minor-number, this
+        * can always be true (??)
+        */
        int (*match_home)(struct supertype *st, char *homehost);
+
+       /* Make one of several generic modifications to metadata
+        * prior to assembly (or other times).
+        *   sparc2.2  - first bug in early 0.90 metadata
+        *   super-minor - change name of 0.90 metadata
+        *   summaries - 'correct' any redundant data
+        *   resync - mark array as dirty to trigger a resync.
+        *   uuid - set new uuid - only 0.90 or 1.x
+        *   name - change the name of the array (where supported)
+        *   homehost - change which host this array is tied to.
+        *   devicesize - If metadata is at start of device, change recorded
+        *               device size to match actual device size
+        *   byteorder - swap bytes for 0.90 metadata
+        *
+        *   force-one  - mark that device as uptodate, not old or failed.
+        *   force-array - mark array as clean if it would not otherwise
+        *               assemble
+        *   assemble   - not sure how this is different from force-one...
+        *   linear-grow-new - add a new device to a linear array, but don't
+        *                   change the size: so superblock still matches
+        *   linear-grow-update - now change the size of the array.
+        */
        int (*update_super)(struct supertype *st, struct mdinfo *info,
                            char *update,
                            char *devname, int verbose,
                            int uuid_set, char *homehost);
+
+       /* Create new metadata for new array as described.  This could
+        * be a new container, or an array in a pre-existing container.
+        * Also used to zero metadata prior to writing it to invalidate old
+        * metadata.
+        */
        int (*init_super)(struct supertype *st, mdu_array_info_t *info,
                          unsigned long long size, char *name,
                          char *homehost, int *uuid);
+
+       /* update the metadata to include new device, either at create or
+        * when hot-adding a spare.
+        */
        void (*add_to_super)(struct supertype *st, mdu_disk_info_t *dinfo,
                             int fd, char *devname);
+
+       /* Write metadata to one device when fixing problems or adding
+        * a new device.
+        */
        int (*store_super)(struct supertype *st, int fd);
+
+       /*  Write all metadata for this array.
+        */
        int (*write_init_super)(struct supertype *st);
        int (*compare_super)(struct supertype *st, struct supertype *tst);
        int (*load_super)(struct supertype *st, int fd, char *devname);
@@ -454,6 +547,17 @@ extern struct superswitch {
 
 extern struct superswitch super_imsm;
 
+/* A supertype holds a particular collection of metadata.
+ * It identifies the metadata type by the superswitch, and the particular
+ * sub-version of that metadata type.
+ * metadata read in or created is stored in 'sb' and 'info'.
+ * There are also fields used by mdmon to track containers.
+ *
+ * A supertype is created by:
+ *   super_by_fd
+ *   guess_super
+ *   dup_super
+ */
 struct supertype {
        struct superswitch *ss;
        int minor_version;