Manage/stop: improve some comments.

This code always confuses me - this might help a bit.

Signed-off-by: NeilBrown <neilb@suse.com>

diff --git a/Manage.c b/Manage.c
index aeb90dd25a079eab5b6307d58e4390cb010f188c..3930f4fd7ad652927cab16b3cdeef8d4a1ad6487 100644 (file)
--- a/Manage.c
+++ b/Manage.c
@@ -216,9 +216,6 @@ int Manage_stop(char *devname, int fd, int verbose, int will_retry)
                return 1;
        }
 
-       /* If this is an mdmon managed array, just write 'inactive'
-        * to the array state and let mdmon clear up.
-        */
        strcpy(devnm, fd2devnm(fd));
        /* Get EXCL access first.  If this fails, then attempting
         * to stop is probably a bad idea.
@@ -242,6 +239,10 @@ int Manage_stop(char *devname, int fd, int verbose, int will_retry)
               && container[0]
               && mdmon_running(container)
               && count) {
+               /* Can't open, so something might be wrong.  However it
+                * is a container, so we might be racing with mdmon, so
+                * retry for a bit.
+                */
                if (fd >= 0)
                        close(fd);
                flush_mdmon(container);
@@ -255,6 +256,9 @@ int Manage_stop(char *devname, int fd, int verbose, int will_retry)
                               devname);
                return 1;
        }
+       /* If this is an mdmon managed array, just write 'inactive'
+        * to the array state and let mdmon clear up.
+        */
        if (mdi &&
            mdi->array.level > 0 &&
            is_subarray(mdi->text_version)) {
@@ -262,7 +266,7 @@ int Manage_stop(char *devname, int fd, int verbose, int will_retry)
                /* This is mdmon managed. */
                close(fd);
 
-               /* As we have an O_EXCL open, any use of the device
+               /* As we had an O_EXCL open, any use of the device
                 * which blocks STOP_ARRAY is probably a transient use,
                 * so it is reasonable to retry for a while - 5 seconds.
                 */
@@ -375,9 +379,20 @@ int Manage_stop(char *devname, int fd, int verbose, int will_retry)
                        size &= ~(chunk1-1);
                        size &= ~(chunk2-1);
                        /* rd1 must be smaller */
+                       /* Reshape may have progressed further backwards than
+                        * recorded, so target even further back (hence "-1")
+                        */
                        position = (position / sectors - 1) * sectors;
+                       /* rd1 is always the conversion factor between 'sync'
+                        * position and 'reshape' position.
+                        * We read 1 "new" stripe worth of data from where-ever,
+                        * and when write out that full stripe.
+                        */
                        sync_max = size - position/rd1;
                } else {
+                       /* Reshape will very likely be beyond position, and it may
+                        * be too late to stop at '+1', so aim for '+2'
+                        */
                        position = (position / sectors + 2) * sectors;
                        sync_max = position/rd1;
                }