MdeModulePkg/.../IdeMode: actualize DRQReady*() comment blocks

The DRQReady() and DRQReady2() functions only differ in that they poll
different status registers for BSY, ERR, and DRQ: the former looks at the
Status Register (clearing interrupt status), while the latter looks at the
Alternate Status Register (not clearing interrupt status).

They both correctly return a unique status code, EFI_NOT_READY, for the

  BSY==0 && ERR==0 && DRQ==0

case; that is, when the device reports "command complete".

However, the functions' leading comments don't explain this case, so it's
easy to miss in callers. Update the comments.

Cc: Feng Tian <feng.tian@intel.com>
Cc: Star Zeng <star.zeng@intel.com>
Cc: John Snow <jsnow@redhat.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Feng Tian <feng.tian@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@19684 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/MdeModulePkg/Bus/Ata/AtaAtapiPassThru/IdeMode.c b/MdeModulePkg/Bus/Ata/AtaAtapiPassThru/IdeMode.c
index f74e5ca373c7308ba88e59d7f6bd24083d3cb1f2..b06f9889ed03abe60a7af0f8b43feeab60c3ad7e 100644 (file)
--- a/MdeModulePkg/Bus/Ata/AtaAtapiPassThru/IdeMode.c
+++ b/MdeModulePkg/Bus/Ata/AtaAtapiPassThru/IdeMode.c
@@ -467,9 +467,18 @@ DRQClear2 (
   @param IdeRegisters     A pointer to EFI_IDE_REGISTERS data structure.\r
   @param Timeout          The time to complete the command, uses 100ns as a unit.\r
 \r
-  @retval EFI_SUCCESS          DRQ bit set within the time out.\r
-  @retval EFI_TIMEOUT          DRQ bit not set within the time out.\r
-  @retval EFI_ABORTED          DRQ bit not set caused by the command abort.\r
+  @retval EFI_SUCCESS           BSY bit cleared and DRQ bit set within the\r
+                                timeout.\r
+\r
+  @retval EFI_TIMEOUT           BSY bit not cleared within the timeout.\r
+\r
+  @retval EFI_ABORTED           Polling abandoned due to command abort.\r
+\r
+  @retval EFI_DEVICE_ERROR      Polling abandoned due to a non-abort error.\r
+\r
+  @retval EFI_NOT_READY         BSY bit cleared within timeout, and device\r
+                                reported "command complete" by clearing DRQ\r
+                                bit.\r
 \r
   @note  Read Status Register will clear interrupt status.\r
 \r
@@ -542,9 +551,19 @@ DRQReady (
   @param IdeRegisters     A pointer to EFI_IDE_REGISTERS data structure.\r
   @param Timeout          The time to complete the command, uses 100ns as a unit.\r
 \r
-  @retval EFI_SUCCESS           DRQ bit set within the time out.\r
-  @retval EFI_TIMEOUT           DRQ bit not set within the time out.\r
-  @retval EFI_ABORTED           DRQ bit not set caused by the command abort.\r
+  @retval EFI_SUCCESS           BSY bit cleared and DRQ bit set within the\r
+                                timeout.\r
+\r
+  @retval EFI_TIMEOUT           BSY bit not cleared within the timeout.\r
+\r
+  @retval EFI_ABORTED           Polling abandoned due to command abort.\r
+\r
+  @retval EFI_DEVICE_ERROR      Polling abandoned due to a non-abort error.\r
+\r
+  @retval EFI_NOT_READY         BSY bit cleared within timeout, and device\r
+                                reported "command complete" by clearing DRQ\r
+                                bit.\r
+\r
   @note  Read Alternate Status Register will not clear interrupt status.\r
 \r
 **/\r