sync the comments of scsilib library class with Mde Library Spec.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6081 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 149 insertions, 137 deletions

diff --git a/MdePkg/Library/UefiScsiLib/UefiScsiLib.c b/MdePkg/Library/UefiScsiLib/UefiScsiLib.c
index f5054de14f..380d195d7e 100644
--- a/MdePkg/Library/UefiScsiLib/UefiScsiLib.c
+++ b/MdePkg/Library/UefiScsiLib/UefiScsiLib.c
@@ -34,16 +34,20 @@
 

 /**

   Function test the ready status of the SCSI unit.

+

+  Submit SCSI test unit ready command with SCSI request packet specified by this scsi command, TimeOut

+  and SenseData, then get the status of the target Scsi unit.

+

   If SenseDataLength is NULL, then ASSERT().

+

   If HostAdapterStatus is NULL, then ASSERT().

+

   If TargetStatus is NULL, then ASSERT().

 

   @param[in]     ScsiIo             A pointer to SCSI IO protocol.

   @param[in]     Timeout            The length of timeout period.

-  @param[in out] SenseData          A pointer to the sense data that 

-                                    was generated by the execution of the SCSI Request Packet.

-  @param[in out] SenseDataLength    On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

+  @param[out]    SenseData          A pointer to output sense data.

+  @param[out]    SenseDataLength    The length of output sense data.

   @param[out]    HostAdapterStatus  The status of Host Adapter.

   @param[out]    TargetStatus       The status of the target.

 

@@ -57,7 +61,7 @@
                                 queued.

   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send 

                                 the SCSI Request Packet.

-  @retval EFI_INVALID_PARAMETER The contents of CommandPacket are invalid, or ScsiIo is NULL.  

+  @retval EFI_INVALID_PARAMETER ScsiIo is NULL.

   @retval EFI_UNSUPPORTED       The command described by the SCSI Request Packet

                                 is not supported by the SCSI initiator(i.e., SCSI 

                                 Host Controller).

@@ -124,38 +128,44 @@ ScsiTestUnitReadyCommand (
 

 /**

   Function to submit SCSI inquiry command.

+

+  Submit SCSI inquiry command with the SCSI request packet specified by this SCSI command and input

+  parameters, then return the status of Scsi unit execution.

+

   If SenseDataLength is NULL, then ASSERT().

+

   If HostAdapterStatus is NULL, then ASSERT().

+

   If TargetStatus is NULL, then ASSERT().

+

   If InquiryDataLength is NULL, then ASSERT().

 

   @param[in]     ScsiIo             SCSI IO Protocol to use

   @param[in]     Timeout            The length of timeout period.

-  @param[in]    SenseData          A pointer to output sense data.

-  @param[in out] SenseDataLength    On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

+  @param[in]     SenseData          A pointer to output sense data.

+  @param[in out] SenseDataLength    The length of output sense data.

   @param[out]    HostAdapterStatus  The status of Host Adapter.

   @param[out]    TargetStatus       The status of the target.

-  @param[in]     InquirydDtaBuffer  A pointer to inquiry data buffer.

+  @param[in out] InquirydataBuffer  A pointer to inquiry data buffer.

   @param[in out] InquiryDataLength  The length of inquiry data buffer.

   @param[in]     EnableVitalProductData  Boolean to enable Vital Product Data.

 

-  @retval EFI_SUCCESS         The status of the unit is tested successfully.

-  @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, 

-                              but the entire DataBuffer could not be transferred.

-                              The actual number of bytes transferred is returned

-                              in TransferLength.

-  @retval EFI_NOT_READY   The SCSI Request Packet could not be sent because 

-                          there are too many SCSI Command Packets already 

-                          queued.

-  @retval EFI_DEVICE_ERROR  A device error occurred while attempting to send 

-                            the SCSI Request Packet.

-  @retval EFI_INVALID_PARAMETER The contents of CommandPacket are invalid, or ScsiIo is NULL.

-  @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet

-                          is not supported by the SCSI initiator(i.e., SCSI 

-                          Host Controller).

-  @retval EFI_TIMEOUT     A timeout occurred while waiting for the SCSI 

-                          Request Packet to execute.

+  @retval EFI_SUCCESS                Command is executed successfully.

+  @retval EFI_BAD_BUFFER_SIZE        The SCSI Request Packet was executed, 

+                                     but the entire DataBuffer could not be transferred.

+                                     The actual number of bytes transferred is returned

+                                     in TransferLength.

+  @retval EFI_NOT_READY              The SCSI Request Packet could not be sent because 

+                                     there are too many SCSI Command Packets already 

+                                     queued.

+  @retval EFI_DEVICE_ERROR           A device error occurred while attempting to send 

+                                     the SCSI Request Packet.

+  @retval EFI_INVALID_PARAMETER      ScsiIo is NULL.

+  @retval EFI_UNSUPPORTED            The command described by the SCSI Request Packet

+                                     is not supported by the SCSI initiator(i.e., SCSI 

+                                     Host Controller).

+  @retval EFI_TIMEOUT                A timeout occurred while waiting for the SCSI 

+                                     Request Packet to execute.

 

 **/

 EFI_STATUS

@@ -228,16 +238,22 @@ ScsiInquiryCommand (
 

 /**

   Function to submit SCSI mode sense 10 command.

+

+  Submit SCSI Mode Sense (10) command with the SCSI request packet specified by this SCSI command and

+  the input parameters, then return the status of Scsi unit execution.

+

   If SenseDataLength is NULL, then ASSERT().

+

   If HostAdapterStatus is NULL, then ASSERT().

+

   If TargetStatus is NULL, then ASSERT().

+

   If DataLength is NULL, then ASSERT().

 

   @param[in]     ScsiIo             A pointer to SCSI IO protocol.

   @param[in]     Timeout            The length of timeout period.

-  @param[in]    SenseData          A pointer to output sense data.

-  @param[in out] SenseDataLength    On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

+  @param[in]     SenseData          A pointer to output sense data.

+  @param[in out] SenseDataLength    The length of output sense data.

   @param[out]    HostAdapterStatus  The status of Host Adapter.

   @param[out]    TargetStatus       The status of the target.

   @param[in]     DataBuffer         A pointer to input data buffer.

@@ -256,7 +272,7 @@ ScsiInquiryCommand (
                                     queued.

   @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send 

                                     the SCSI Request Packet.

-  @retval EFI_INVALID_PARAMETER     The contents of CommandPacket are invalid, or ScsiIo is NULL.  

+  @retval EFI_INVALID_PARAMETER     ScsiIo is NULL. 

   @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet

                                     is not supported by the SCSI initiator(i.e., SCSI 

                                     Host Controller).

@@ -339,35 +355,31 @@ ScsiModeSense10Command (
 

 /**

   Function to submit SCSI request sense command.

+

+  Submit SCSI request sense command with the SCSI requested packet specified by this

+  SCSI command, TimeOut and SenseData, and then return the status of scsi unit execution.

+

   If SenseDataLength is NULL, then ASSERT().

+  

   If HostAdapterStatus is NULL, then ASSERT().

+  

   If TargetStatus is NULL, then ASSERT().

 

-  @param[in]     ScsiIo             A pointer to SCSI IO protocol.

-  @param[in]     Timeout            The length of timeout period.

-  @param[in]     SenseData          A pointer to output sense data.

-  @param[in out] SenseDataLength    On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

-  @param[out]    HostAdapterStatus  The status of Host Adapter.

-  @param[out]    TargetStatus       The status of the target.

-

-  @retval EFI_SUCCESS        Valid data returned

-  @retval EFI_SUCCESS        The status of the unit is tested successfully.

-  @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed, 

-                                    but the entire DataBuffer could not be transferred.

-                                    The actual number of bytes transferred is returned

-                                    in TransferLength.

-  @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because 

-                                    there are too many SCSI Command Packets already 

-                                    queued.

-  @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send 

-                                    the SCSI Request Packet.

-  @retval EFI_INVALID_PARAMETER     The contents of CommandPacket are invalid, or ScsiIo is NULL.

-  @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet

-                                    is not supported by the SCSI initiator(i.e., SCSI 

-                                    Host Controller).

-  @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI 

-                                    Request Packet to execute.

+  @param[in]       ScsiIo               A pointer to SCSI IO protocol.

+  @param[in]       Timeout              The length of timeout period.

+  @param[in]       SenseData            A pointer to output sense data.

+  @param[in out]   SenseDataLength      The length of output sense data.

+  @param[out]      HostAdapterStatus    The status of Host Adapter.

+  @param[out]      TargetStatus         The status of the target.

+

+  @retval EFI_SUCCESS                   Command is executed successfully.

+  @retval EFI_NOT_READY                 The SCSI Request Packet could not be sent because there are

+                                        too many SCSI Command Packets already queued.

+  @retval EFI_DEVICE_ERROR              A device error occurred while attempting to send SCSI Request Packet.

+  @retval EFI_UNSUPPORTED               The command described by the SCSI Request Packet is not supported by

+                                        the SCSI initiator(i.e., SCSI  Host Controller)

+  @retval EFI_TIMEOUT                   A timeout occurred while waiting for the SCSI Request Packet to execute.

+  @retval EFI_INVALID_PARAMETER         ScsiIo is NULL.

 

 **/

 EFI_STATUS

@@ -430,38 +442,38 @@ ScsiRequestSenseCommand (
 

 /**

   Function to submit read capacity command.

+

+  Submit SCSI read capacity command with the SCSI request packet specified by this SCSI 

+  command and the input parameters, and then return the status of Scsi unit execution.

+

   If SenseDataLength is NULL, then ASSERT().

+

   If HostAdapterStatus is NULL, then ASSERT().

+

   If TargetStatus is NULL, then ASSERT().

+

   If DataLength is NULL, then ASSERT().

 

-  @param[in]     ScsiIo             A pointer to SCSI IO protocol.

-  @param[in]     Timeout            The length of timeout period.

-  @param[in]    SenseData          A pointer to output sense data.

-  @param[in out] SenseDataLength    On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

-  @param[out]    HostAdapterStatus  The status of Host Adapter.

-  @param[out]    TargetStatus       The status of the target.

-  @param[out]    DataBuffer         A pointer to a data buffer.

-  @param[in out] DataLength         The length of data buffer.

-  @param[in]     PMI                Partial medium indicator.

-

-  @retval  EFI_SUCCESS                The status of the unit is tested successfully.

-  @retval  EFI_BAD_BUFFER_SIZE        The SCSI Request Packet was executed, 

-                                      but the entire DataBuffer could not be transferred.

-                                      The actual number of bytes transferred is returned

-                                      in TransferLength.

-  @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because 

-                                      there are too many SCSI Command Packets already 

-                                      queued.

-  @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send 

-                                      the SCSI Request Packet.

-  @retval  EFI_INVALID_PARAMETER      The contents of CommandPacket are invalid, or ScsiIo is NULL.

-  @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet

-                                      is not supported by the SCSI initiator(i.e., SCSI 

-                                      Host Controller).

-  @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI 

-                                      Request Packet to execute.

+  @param[in]     ScsiIo               A pointer to SCSI IO protocol.

+  @param[in]     Timeout              The length of timeout period.

+  @param[in]     SenseData            A pointer to output sense data.

+  @param[in out] SenseDataLength      The length of output sense data.

+  @param[out]    HostAdapterStatus    The status of Host Adapter.

+  @param[out]    TargetStatus         The status of the target.

+  @param[out]    DataBuffer           A pointer to a data buffer.

+  @param[in out] DataLength           The length of data buffer.

+  @param[in]     PMI                  Partial medium indicator.

+

+  @retval  EFI_SUCCESS                Command is executed successfully.

+  @retval  EFI_WARN_BUFFER_TOO_SMALL  The SCSI Request Packet was executed, but the entire DataBuffer could

+                                      not be transferred. The actual number of bytes transferred is returned in DataLength.

+  @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because there are too many 

+                                      SCSI Command Packets already queued.

+  @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send SCSI Request Packet.

+  @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet is not supported by 

+                                      the SCSI initiator(i.e., SCSI  Host Controller)

+  @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI Request Packet to execute.

+  @retval  EFI_INVALID_PARAMETER      ScsiIo is NULL.

 

 **/

 EFI_STATUS

@@ -536,39 +548,39 @@ ScsiReadCapacityCommand (
 

 /**

   Function to submit read 10 command.

+

+  Submit SCSI read (10) command with the SCSI request packet specified by this SCSI command 

+  and the input parameters, and then return the status of Scsi unit execution.

+

   If SenseDataLength is NULL, then ASSERT().

+

   If HostAdapterStatus is NULL, then ASSERT().

+

   If TargetStatus is NULL, then ASSERT().

-  If DataLength is NULL, then ASSERT().

 

-  @param[in]     ScsiIo             A pointer to SCSI IO protocol.

-  @param[in]     Timeout            The length of timeout period.

-  @param[in]     SenseData          A pointer to output sense data.

-  @param[in out] SenseDataLength    On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

-  @param[out]    HostAdapterStatus  The status of Host Adapter.

-  @param[out]    TargetStatus       The status of the target.

-  @param[out]    DataBuffer         Read 10 command data.

-  @param[in out] DataLength         The length of data buffer.

-  @param[in]     StartLba           The start address of LBA.

-  @param[in]     SectorSize         The sector size.

+  If DataLength is NULL, then ASSERT().

 

-  @retval EFI_SUCCESS               The status of the unit is tested successfully.

-  @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed, 

-                                    but the entire DataBuffer could not be transferred.

-                                    The actual number of bytes transferred is returned

-                                    in TransferLength.

-  @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because 

-                                    there are too many SCSI Command Packets already 

-                                    queued.

-  @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send 

-                                    the SCSI Request Packet.

-  @retval EFI_INVALID_PARAMETER     The contents of CommandPacket are invalid, or ScsiIo is NULL.

-  @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet

-                                    is not supported by the SCSI initiator(i.e., SCSI 

-                                    Host Controller).

-  @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI 

-                                    Request Packet to execute.

+  @param[in]     ScsiIo               A pointer to SCSI IO protocol.

+  @param[in]     Timeout              The length of timeout period.

+  @param[in]     SenseData            A pointer to output sense data.

+  @param[in out] SenseDataLength      The length of output sense data.

+  @param[out]    HostAdapterStatus    The status of Host Adapter.

+  @param[out]    TargetStatus         The status of the target.

+  @param[out]    DataBuffer           Read 10 command data.

+  @param[in out] DataLength           The length of data buffer.

+  @param[in]     StartLba             The start address of LBA.

+  @param[in]     SectorSize           The sector size.

+

+  @retval  EFI_SUCCESS                Command is executed successfully.

+  @retval  EFI_WARN_BUFFER_TOO_SMALL  The SCSI Request Packet was executed, but the entire DataBuffer could

+                                      not be transferred. The actual number of bytes transferred is returned in DataLength.

+  @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because there are too many 

+                                      SCSI Command Packets already queued.

+  @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send SCSI Request Packet.

+  @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet is not supported by 

+                                      the SCSI initiator(i.e., SCSI  Host Controller)

+  @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI Request Packet to execute.

+  @retval  EFI_INVALID_PARAMETER      ScsiIo is NULL.

 

 **/

 EFI_STATUS

@@ -642,39 +654,39 @@ ScsiRead10Command (
 

 /**

   Function to submit SCSI write 10 command.

+

+  Submit SCSI write (10) command with the SCSI request packet specified by this SCSI command and the

+  input parameters, and then return the status of Scsi unit execution.

+

   If SenseDataLength is NULL, then ASSERT().

+

   If HostAdapterStatus is NULL, then ASSERT().

+

   If TargetStatus is NULL, then ASSERT().

-  If DataLength is NULL, then ASSERT().

 

-  @param[in]     ScsiIo             SCSI IO Protocol to use

-  @param[in]     Timeout            The length of timeout period.

-  @param[in]    SenseData          A pointer to output sense data.

-  @param[in out]  SenseDataLength   On input, the length in bytes of the SenseData buffer. On

-                                    output, the number of bytes written to the SenseData buffer.

-  @param[out]    HostAdapterStatus  The status of Host Adapter.

-  @param[out]    TargetStatus       The status of the target.

-  @param[out]    DataBuffer         A pointer to a data buffer.

-  @param[in out] DataLength         The length of data buffer.

-  @param[in]     StartLba           The start address of LBA.

-  @param[in]     SectorSize         The sector size.

+  If DataLength is NULL, then ASSERT().

 

-  @retval EFI_SUCCESS               The status of the unit is tested successfully.

-  @retval EFI_BAD_BUFFER_SIZE       The SCSI Request Packet was executed, 

-                                    but the entire DataBuffer could not be transferred.

-                                    The actual number of bytes transferred is returned

-                                    in InTransferLength.

-  @retval EFI_NOT_READY             The SCSI Request Packet could not be sent because 

-                                    there are too many SCSI Command Packets already 

-                                    queued.

-  @retval EFI_DEVICE_ERROR          A device error occurred while attempting to send 

-                                    the SCSI Request Packet.

-  @retval EFI_INVALID_PARAMETER     The contents of CommandPacket are invalid, or ScsiIo is NULL.

-  @retval EFI_UNSUPPORTED           The command described by the SCSI Request Packet

-                                    is not supported by the SCSI initiator(i.e., SCSI 

-                                    Host Controller).

-  @retval EFI_TIMEOUT               A timeout occurred while waiting for the SCSI 

-                                    Request Packet to execute.

+  @param[in]     ScsiIo               SCSI IO Protocol to use

+  @param[in]     Timeout              The length of timeout period.

+  @param[in]     SenseData            A pointer to output sense data.

+  @param[in out] SenseDataLength      The length of output sense data.

+  @param[out]    HostAdapterStatus    The status of Host Adapter.

+  @param[out]    TargetStatus         The status of the target.

+  @param[out]    DataBuffer           A pointer to a data buffer.

+  @param[in out] DataLength           The length of data buffer.

+  @param[in]     StartLba             The start address of LBA.

+  @param[in]     SectorSize           The sector size.

+

+  @retval  EFI_SUCCESS                Command is executed successfully.

+  @retval  EFI_WARN_BUFFER_TOO_SMALL  The SCSI Request Packet was executed, but the entire DataBuffer could

+                                      not be transferred. The actual number of bytes transferred is returned in DataLength.

+  @retval  EFI_NOT_READY              The SCSI Request Packet could not be sent because there are too many 

+                                      SCSI Command Packets already queued.

+  @retval  EFI_DEVICE_ERROR           A device error occurred while attempting to send SCSI Request Packet.

+  @retval  EFI_UNSUPPORTED            The command described by the SCSI Request Packet is not supported by 

+                                      the SCSI initiator(i.e., SCSI  Host Controller)

+  @retval  EFI_TIMEOUT                A timeout occurred while waiting for the SCSI Request Packet to execute.

+  @retval  EFI_INVALID_PARAMETER      ScsiIo is NULL.

 

 **/

 EFI_STATUS