ata: libata-eh: Clarify ata_eh_qc_retry() behavior at call site

While the function documentation for ata_eh_qc_retry() is clear,
from simply reading the single function that calls ata_eh_qc_retry(),
it is not clear that ata_eh_qc_retry() might not retry the command.

Add a comment in the single function that calls ata_eh_qc_retry() to
clarify the behavior.

[Damien] Added curly braces to "if () else" with multi-line comment.

Signed-off-by: Niklas Cassel <niklas.cassel@wdc.com>
Signed-off-by: Damien Le Moal <dlemoal@kernel.org>

diff --git a/drivers/ata/libata-eh.c b/drivers/ata/libata-eh.c
index a6c9018..c7336a0 100644 (file)
--- a/drivers/ata/libata-eh.c
+++ b/drivers/ata/libata-eh.c
@@ -3813,16 +3813,29 @@ void ata_eh_finish(struct ata_port *ap)
                         * generate sense data in this function,
                         * considering both err_mask and tf.
                         */
-                       if (qc->flags & ATA_QCFLAG_RETRY)
+                       if (qc->flags & ATA_QCFLAG_RETRY) {
+                               /*
+                                * Since qc->err_mask is set, ata_eh_qc_retry()
+                                * will not increment scmd->allowed, so upper
+                                * layer will only retry the command if it has
+                                * not already been retried too many times.
+                                */
                                ata_eh_qc_retry(qc);
-                       else
+                       } else {
                                ata_eh_qc_complete(qc);
+                       }
                } else {
                        if (qc->flags & ATA_QCFLAG_SENSE_VALID) {
                                ata_eh_qc_complete(qc);
                        } else {
                                /* feed zero TF to sense generation */
                                memset(&qc->result_tf, 0, sizeof(qc->result_tf));
+                               /*
+                                * Since qc->err_mask is not set,
+                                * ata_eh_qc_retry() will increment
+                                * scmd->allowed, so upper layer is guaranteed
+                                * to retry the command.
+                                */
                                ata_eh_qc_retry(qc);
                        }
                }