Fixed comments to follow coding standard.

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

1 files changed, 243 insertions, 181 deletions

diff --git a/MdePkg/Include/Library/ScsiLib.h b/MdePkg/Include/Library/ScsiLib.h
index 5c2e60b008..607a67cef8 100644
--- a/MdePkg/Include/Library/ScsiLib.h
+++ b/MdePkg/Include/Library/ScsiLib.h
@@ -31,6 +31,35 @@
 //

 #define EfiScsiStallSeconds(a)  (a) * EFI_SCSI_STALL_1_SECOND

 

+

+/**
+  Function test the ready status of the SCSI unit.

+
+  @param[in]     ScsiIo             A pointer to SCSI IO protocol.
+  @param[in]     Timeout            The length of timeout period.
+  @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.
+
+  @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.  

+  @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

 SubmitTestUnitReadyCommand (

   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,

@@ -39,29 +68,40 @@ SubmitTestUnitReadyCommand (
   OUT UINT8                 *SenseDataLength,

   OUT UINT8                 *HostAdapterStatus,

   OUT UINT8                 *TargetStatus

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo            - TODO: add argument description

-  Timeout           - TODO: add argument description

-  SenseData         - TODO: add argument description

-  SenseDataLength   - TODO: add argument description

-  HostAdapterStatus - TODO: add argument description

-  TargetStatus      - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

-

---*/

-;

-

+  );

+

+

+/**
+  Function to submit SCSI inquiry command.

+
+  @param[in]     ScsiIo             SCSI IO Protocol to use
+  @param[in]     Timeout            The length of timeout period.
+  @param[out]    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,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.  

+  @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

 SubmitInquiryCommand (

   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,

@@ -73,32 +113,42 @@ SubmitInquiryCommand (
   IN OUT VOID               *InquiryDataBuffer,

   IN OUT UINT32             *InquiryDataLength,

   IN  BOOLEAN               EnableVitalProductData

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo                  - TODO: add argument description

-  Timeout                 - TODO: add argument description

-  SenseData               - TODO: add argument description

-  SenseDataLength         - TODO: add argument description

-  HostAdapterStatus       - TODO: add argument description

-  TargetStatus            - TODO: add argument description

-  InquiryDataBuffer       - TODO: add argument description

-  InquiryDataLength       - TODO: add argument description

-  EnableVitalProductData  - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

-

---*/

-;

-

+  );

+

+

+/**
+  Function to submit SCSI mode sense 10 command.

+
+  @param[in]     ScsiIo             A pointer to SCSI IO protocol.
+  @param[in]     Timeout            The length of timeout period.
+  @param[out]    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.
+  @param[in,out] DataLength         The length of input data buffer.
+  @param[in]     DBDField           The DBD Field (Optional).
+  @param[in]     PageControl        Page Control.
+  @param[in]     PageCode           Page code.
+
+  @retval EFI_SUCCESS               The status of the unit is tested 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 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.  

+  @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

 SubmitModeSense10Command (

   IN  EFI_SCSI_IO_PROTOCOL    *ScsiIo,

@@ -112,34 +162,45 @@ SubmitModeSense10Command (
   IN  UINT8                   DBDField, OPTIONAL

   IN  UINT8                   PageControl,

   IN  UINT8                   PageCode

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo            - TODO: add argument description

-  Timeout           - TODO: add argument description

-  SenseData         - TODO: add argument description

-  SenseDataLength   - TODO: add argument description

-  HostAdapterStatus - TODO: add argument description

-  TargetStatus      - TODO: add argument description

-  DataBuffer        - TODO: add argument description

-  DataLength        - TODO: add argument description

-  DBDField          - TODO: add argument description

-  PageControl       - TODO: add argument description

-  PageCode          - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

-

---*/

-;

-

+  );

+

+

+

+/**
+  Function to submit SCSI request sense command.

+  ScsiIo               - A pointer to SCSI IO protocol.

+  Timeout              - The length of timeout period.

+  SenseData            - A pointer to output sense data.

+  SenseDataLength      - The length of output sense data.

+  HostAdapterStatus    - The status of Host Adapter.

+  TargetStatus         - The status of the target.

+
+  @param[in]     ScsiIo             SCSI IO Protocol to use
+  @param[in]     Timeout            TODO:
+  @param[out]    SenseData          TODO:
+  @param[in,out] SenseDataLength    TODO:
+  @param[out]    HostAdapterStatus  TODO:
+  @param[out]    TargetStatus       TODO:
+
+  @retval EFI_SUCCESS        Valid data returned
+  @retval EFI_SUCCESS        The status of the unit is tested 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 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.  

+  @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

 SubmitRequestSenseCommand (

   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,

@@ -148,32 +209,40 @@ SubmitRequestSenseCommand (
   IN OUT UINT8              *SenseDataLength,

   OUT UINT8                 *HostAdapterStatus,

   OUT UINT8                 *TargetStatus

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo            - TODO: add argument description

-  Timeout           - TODO: add argument description

-  SenseData         - TODO: add argument description

-  SenseDataLength   - TODO: add argument description

-  HostAdapterStatus - TODO: add argument description

-  TargetStatus      - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

-

---*/

-;

-

-//

-// Commands for direct access command

-//

+  );

+

+

+/**
+  Function to submit read capacity command.

+

+  @param[in]     ScsiIo             A pointer to SCSI IO protocol.
+  @param[in]     Timeout            The length of timeout period.
+  @param[out]    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                The status of the unit is tested 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 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.  

+  @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

 SubmitReadCapacityCommand (

   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,

@@ -185,32 +254,41 @@ SubmitReadCapacityCommand (
   OUT VOID                  *DataBuffer,

   IN OUT UINT32             *DataLength,

   IN  BOOLEAN               PMI

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo            - TODO: add argument description

-  Timeout           - TODO: add argument description

-  SenseData         - TODO: add argument description

-  SenseDataLength   - TODO: add argument description

-  HostAdapterStatus - TODO: add argument description

-  TargetStatus      - TODO: add argument description

-  DataBuffer        - TODO: add argument description

-  DataLength        - TODO: add argument description

-  PMI               - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

-

---*/

-;

-

+  );

+

+

+/**
+  Function to submit read 10 command.

+
+  @param[in]     ScsiIo             A pointer to SCSI IO protocol.
+  @param[in]     Timeout            The length of timeout period.
+  @param[out]    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               The status of the unit is tested 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 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.  

+  @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

 SubmitRead10Command (

   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,

@@ -223,33 +301,41 @@ SubmitRead10Command (
   IN OUT UINT32             *DataLength,

   IN  UINT32                StartLba,

   IN  UINT32                SectorSize

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo            - TODO: add argument description

-  Timeout           - TODO: add argument description

-  SenseData         - TODO: add argument description

-  SenseDataLength   - TODO: add argument description

-  HostAdapterStatus - TODO: add argument description

-  TargetStatus      - TODO: add argument description

-  DataBuffer        - TODO: add argument description

-  DataLength        - TODO: add argument description

-  StartLba          - TODO: add argument description

-  SectorSize        - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

-

---*/

-;

-

+  );

+

+

+/**
+  Function to submit SCSI write 10 command.

+
+  @param[in]     ScsiIo             SCSI IO Protocol to use
+  @param[in]     Timeout            The length of timeout period.
+  @param[out]    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               The status of the unit is tested 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 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.  

+  @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

 SubmitWrite10Command (

   IN  EFI_SCSI_IO_PROTOCOL  *ScsiIo,

@@ -262,31 +348,7 @@ SubmitWrite10Command (
   IN OUT UINT32             *DataLength,

   IN  UINT32                StartLba,

   IN  UINT32                SectorSize

-  )

-/*++

-

-Routine Description:

-

-  TODO: Add function description

-

-Arguments:

-

-  ScsiIo            - TODO: add argument description

-  Timeout           - TODO: add argument description

-  SenseData         - TODO: add argument description

-  SenseDataLength   - TODO: add argument description

-  HostAdapterStatus - TODO: add argument description

-  TargetStatus      - TODO: add argument description

-  DataBuffer        - TODO: add argument description

-  DataLength        - TODO: add argument description

-  StartLba          - TODO: add argument description

-  SectorSize        - TODO: add argument description

-

-Returns:

-

-  TODO: add return values

+  );

 

---*/

-;

 

 #endif