From d5954c618f10c9f75a4d125985550e694c7a3f22 Mon Sep 17 00:00:00 2001 From: jji4 Date: Mon, 17 Nov 2008 11:24:14 +0000 Subject: Code Scrub: The code of MdePkg\Library\UefiScsiLib\ and MdePkg\Library\UefiUsbLib has been checked and modified according to MDE_Library_Spec_0.61h-4.doc. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6561 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Library/UefiScsiLib.h | 530 +++++++++++++--------- MdePkg/Include/Library/UefiUsbLib.h | 471 ++++++++++++------- MdePkg/Library/UefiScsiLib/UefiScsiLib.c | 598 ++++++++++++++----------- MdePkg/Library/UefiUsbLib/Hid.c | 242 ++++++---- MdePkg/Library/UefiUsbLib/UefiUsbLib.inf | 1 + MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h | 9 +- MdePkg/Library/UefiUsbLib/UsbDxeLib.c | 369 +++++++++------ 7 files changed, 1334 insertions(+), 886 deletions(-) diff --git a/MdePkg/Include/Library/UefiScsiLib.h b/MdePkg/Include/Library/UefiScsiLib.h index f1d899d38b..d721735b46 100644 --- a/MdePkg/Include/Library/UefiScsiLib.h +++ b/MdePkg/Include/Library/UefiScsiLib.h @@ -2,7 +2,7 @@ Provides the functions to submit Scsi commands defined in SCSI-2 specification for scsi device. -Copyright (c) 2006 - 2008, Intel Corporation +Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -34,189 +34,291 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** - 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. + Execute Test Unit Ready SCSI command on a specific SCSI target. + Executes the Test Unit Ready command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). 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[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 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 the SCSI I/O Protocol instance + for the specific SCSI target. + @param[in] Timeout The timeout in 100 ns units to use for the execution + of this SCSI Request Packet. A Timeout value of + zero means that this function will wait indefinitely + for the SCSI Request Packet to execute. If Timeout + is greater than zero, then this function will return + EFI_TIMEOUT if the time required to execute the SCSI + Request Packet is greater than Timeout. + @param[in, out] SenseData A pointer to sense data that was generated by + the execution of the SCSI Request Packet. This + buffer must be allocated by the caller. + If SenseDataLength is 0, then this parameter is + optional and may be NULL. + @param[in, out] SenseDataLength On input, a pointer to the length in bytes of + the SenseData buffer. On output, a poiinter to + the number of bytes written to the SenseData buffer. + @param[out] HostAdapterStatus The status of the SCSI Host Controller that produces + the SCSI bus containing the SCSI target specified by + ScsiIo when the SCSI Request Packet was executed. + See the EFI SCSI I/O Protocol in the UEFI Specification + for details on the possible return values. + @param[out] TargetStatus The status returned by the SCSI target specified + by ScsiIo when the SCSI Request Packat was executed + on the SCSI Host Controller. See the EFI SCSI I/O + Protocol in the UEFI Specification for details on + the possible return values. + + @retval EFI_SUCCESS The command was executed successfully. + See HostAdapterStatus, TargetStatus, SenseDataLength, + and SenseData in that order for additional status + information. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because + there are too many SCSI Command Packets already + queued. The SCSI Request Packet was not sent, so + no additional status information is available. + The caller may retry again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send + SCSI Request Packet. See HostAdapterStatus, + TargetStatus, SenseDataLength, and SenseData in that + order for additional status information. + @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet + is not supported by the SCSI initiator(i.e., SCSI + Host Controller). The SCSI Request Packet was not + sent, so no additional status information is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request + Packet to execute. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for + additional status information. + @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. **/ EFI_STATUS EFIAPI ScsiTestUnitReadyCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus ); /** - 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. + Execute Inquiry SCSI command on a specific SCSI target. + Executes the Inquiry command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). 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 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 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. + @param[in] ScsiIo A pointer to the SCSI I/O Protocol instance + for the specific SCSI target. + @param[in] Timeout The timeout in 100 ns units to use for the + execution of this SCSI Request Packet. A Timeout + value of zero means that this function will wait + indefinitely for the SCSI Request Packet to execute. + If Timeout is greater than zero, then this function + will return EFI_TIMEOUT if the time required to + execute the SCSI Request Packet is greater than Timeout. + @param[in, out] SenseData A pointer to sense data that was generated + by the execution of the SCSI Request Packet. + This buffer must be allocated by the caller. + If SenseDataLength is 0, then this parameter + is optional and may be NULL. + @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 the SCSI Host Controller that + produces the SCSI bus containing the SCSI + target specified by ScsiIo when the SCSI + Request Packet was executed. See the EFI + SCSI I/O Protocol in the UEFI Specification + for details on the possible return values. + @param[out] TargetStatus The status returned by the SCSI target specified + by ScsiIo when the SCSI Request Packat was + executed on the SCSI Host Controller. + See the EFI SCSI I/O Protocol in the UEFI + Specification for details on the possible + return values. + @param[in, out] InquiryDataBuffer A pointer to inquiry data that was generated + by the execution of the SCSI Request Packet. + This buffer must be allocated by the caller. + If InquiryDataLength is 0, then this parameter + is optional and may be NULL. + @param[in, out] InquiryDataLength On input, a pointer to the length in bytes + of the InquiryDataBuffer buffer. + On output, a pointer to the number of bytes + written to the InquiryDataBuffer buffer. + @param[in] EnableVitalProductData If TRUE, then the supported vital product + data is returned in InquiryDataBuffer. + If FALSE, then the standard inquiry data is + returned in InquiryDataBuffer. + + @retval EFI_SUCCESS The command was executed successfully. See HostAdapterStatus, + TargetStatus, SenseDataLength, and SenseData in that order + for additional status information. + @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, but the entire + InquiryDataBuffer could not be transferred. The actual + number of bytes transferred is returned in InquiryDataLength. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because there + are too many SCSI Command Packets already queued. + The SCSI Request Packet was not sent, so no additional + status information is available. The caller may retry again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send SCSI + Request Packet. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for additional + status information. + @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet is not + supported by the SCSI initiator(i.e., SCSI Host Controller). + The SCSI Request Packet was not sent, so no additional + status information is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request + Packet to execute. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for + additional status information. **/ EFI_STATUS EFIAPI ScsiInquiryCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - IN OUT VOID *InquiryDataBuffer, - IN OUT UINT32 *InquiryDataLength, - IN BOOLEAN EnableVitalProductData + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *InquiryDataBuffer, OPTIONAL + IN OUT UINT32 *InquiryDataLength, + IN BOOLEAN EnableVitalProductData ); /** - 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. - + Execute Mode Sense(10) SCSI command on a specific SCSI target. + + Executes the SCSI Mode Sense(10) command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout + after Timeout 100 ns units. The DBDField, PageControl, and PageCode parameters + are used to construct the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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 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_BAD_BUFFER_SIZE The SCSI Request Packet was executed, - but the entire DataBuffer could not be transferred. + + @param[in] ScsiIo A pointer to the SCSI I/O Protocol instance + for the specific SCSI target. + @param[in] Timeout The timeout in 100 ns units to use for the + execution of this SCSI Request Packet. A Timeout + value of zero means that this function will wait + indefinitely for the SCSI Request Packet to execute. + If Timeout is greater than zero, then this function + will return EFI_TIMEOUT if the time required to + execute the SCSI Request Packet is greater than Timeout. + @param[in,out] SenseData A pointer to sense data that was generated + by the execution of the SCSI Request Packet. + This buffer must be allocated by the caller. + If SenseDataLength is 0, then this parameter + is optional and may be NULL. + @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 the SCSI Host Controller that + produces the SCSI bus containing the SCSI target + specified by ScsiIo when the SCSI Request Packet + was executed. See the EFI SCSI I/O Protocol in the + UEFI Specification for details on the possible + return values. + @param[out] TargetStatus The status returned by the SCSI target specified + by ScsiIo when the SCSI Request Packat was executed + on the SCSI Host Controller. See the EFI SCSI + I/O Protocol in the UEFI Specification for details + on the possible return values. + @param[in,out] DataBuffer A pointer to data that was generated by the + execution of the SCSI Request Packet. This + buffer must be allocated by the caller. If + DataLength is 0, then this parameter is optional + and may be NULL. + @param[in,out] DataLength On input, a pointer to the length in bytes of + the DataBuffer buffer. On output, a pointer + to the number of bytes written to the DataBuffer + buffer. + @param[in] DBDField Specifies the DBD field of the CDB for this SCSI Command. + @param[in] PageControl Specifies the PC field of the CDB for this SCSI Command. + @param[in] PageCode Specifies the Page Control field of the CDB for this SCSI Command. + + @retval EFI_SUCCESS The command was executed successfully. + See HostAdapterStatus, TargetStatus, SenseDataLength, + and SenseData in that order for additional status information. + @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. + in DataLength. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because + there are too many SCSI Command Packets already queued. + The SCSI Request Packet was not sent, so no additional + status information is available. The caller may retry + again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send + SCSI Request Packet. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for + additional status information. @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. + is not supported by the SCSI initiator(i.e., SCSI + Host Controller). The SCSI Request Packet was not + sent, so no additional status information is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI + Request Packet to execute. See HostAdapterStatus, + TargetStatus, SenseDataLength, and SenseData in that + order for additional status information. **/ EFI_STATUS EFIAPI ScsiModeSense10Command ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - IN VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN UINT8 DBDField, OPTIONAL - IN UINT8 PageControl, - IN UINT8 PageCode + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN UINT8 DBDField, OPTIONAL + IN UINT8 PageControl, + IN UINT8 PageCode ); /** - 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. + Execute Request Sense SCSI command on a specific SCSI target. + Executes the Request Sense command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). 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 The length of output sense data. + @param[in, 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. @@ -227,44 +329,42 @@ ScsiModeSense10Command ( @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 EFIAPI ScsiRequestSenseCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus ); /** - 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. + Execute Read Capacity SCSI command on a specific SCSI target. + Executes the SCSI Read Capacity command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after + Timeout 100 ns units. The PMI parameter is used to construct the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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] ScsiIo A pointer to SCSI IO protocol. + @param[in] Timeout The length of timeout period. + @param[in, 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[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in, out] DataBuffer A pointer to a data buffer. @param[in, out] DataLength The length of data buffer. - @param[in] PMI Partial medium indicator. + @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 @@ -275,48 +375,48 @@ ScsiRequestSenseCommand ( @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 EFIAPI ScsiReadCapacityCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - OUT VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN BOOLEAN PMI + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN BOOLEAN PMI ); /** - 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. - + Execute Read(10) SCSI command on a specific SCSI target. + + Executes the SCSI Read(10) command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout + after Timeout 100 ns units. The StartLba and SectorSize parameters are used to + construct the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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] ScsiIo A pointer to SCSI IO protocol. + @param[in] Timeout The length of timeout period. + @param[in, 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[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in, 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. + @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 @@ -327,49 +427,48 @@ ScsiReadCapacityCommand ( @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 EFIAPI ScsiRead10Command ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - OUT VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN UINT32 StartLba, - IN UINT32 SectorSize + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN UINT32 StartLba, + IN UINT32 SectorSize ); /** - 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. - + Execute Write(10) SCSI command on a specific SCSI target. + + Executes the SCSI Write(10) command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after + Timeout 100 ns units. The StartLba and SectorSize parameters are used to construct + the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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] ScsiIo SCSI IO Protocol to use + @param[in] Timeout The length of timeout period. + @param[in, 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[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in, 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. + @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 @@ -380,22 +479,21 @@ ScsiRead10Command ( @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 EFIAPI ScsiWrite10Command ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - OUT VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN UINT32 StartLba, - IN UINT32 SectorSize + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN UINT32 StartLba, + IN UINT32 SectorSize ); diff --git a/MdePkg/Include/Library/UefiUsbLib.h b/MdePkg/Include/Library/UefiUsbLib.h index f1fdc3d073..2a6730d76a 100644 --- a/MdePkg/Include/Library/UefiUsbLib.h +++ b/MdePkg/Include/Library/UefiUsbLib.h @@ -18,6 +18,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define __USB_DXE_LIB_H__ #include +#include /// /// define the timeout time as 3ms @@ -25,57 +26,78 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define TIMEOUT_VALUE 3 * 1000 /** - Get Hid Descriptor. + Get the descriptor of the specified USB HID interface. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param InterfaceNum Hid interface number. - @param HidDescriptor Caller allocated buffer to store Usb hid descriptor if - successfully returned. + Submit a USB get HID descriptor request for the USB device specified by UsbIo + and Interface and return the HID descriptor in HidDescriptor. + If UsbIo is NULL, then ASSERT(). + If HidDescriptor is NULL, then ASSERT(). - @return Status of getting HID descriptor through USB I/O - protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the HID interface on the USB target. + @param HidDescriptor Pointer to the USB HID descriptor that was retrieved from + the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR + is defined in the MDE Package Industry Standard include file Usb.h. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS EFIAPI UsbGetHidDescriptor ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 InterfaceNum, + IN UINT8 Interface, OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor ); /** - get Report Class descriptor. + Get the report descriptor of the specified USB HID interface. + + Submit a USB get HID report descriptor request for the USB device specified by + UsbIo and Interface and return the report descriptor in DescriptorBuffer. + If UsbIo is NULL, then ASSERT(). + If DescriptorBuffer is NULL, then ASSERT(). - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param InterfaceNum Report interface number. - @param DescriptorSize Length of DescriptorBuffer. - @param DescriptorBuffer Caller allocated buffer to store Usb report descriptor - if successfully returned. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param DescriptorLength The size, in bytes, of DescriptorBuffer. + @param DescriptorBuffer A pointer to the buffer to store the report class descriptor. - @return Status of getting Report Class descriptor through USB - I/O protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed because the + buffer specifed by DescriptorLength and DescriptorBuffer + is not large enough to hold the result of the request. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS EFIAPI UsbGetReportDescriptor ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 InterfaceNum, - IN UINT16 DescriptorSize, + IN UINT8 Interface, + IN UINT16 DescriptorLength, OUT UINT8 *DescriptorBuffer ); /** - Get Hid Protocol Request. + Get the HID protocol of the specified USB HID interface. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to get protocol. - @param Protocol Protocol value returned. + Submit a USB get HID protocol request for the USB device specified by UsbIo + and Interface and return the protocol retrieved in Protocol. + If UsbIo is NULL, then ASSERT(). + If Protocol is NULL, then ASSERT(). - @return Status of getting Protocol Request through USB I/O - protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param Protocol A pointer to the protocol for the specified USB target. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -87,14 +109,19 @@ UsbGetProtocolRequest ( ); /** - Set Hid Protocol Request. + Set the HID protocol of the specified USB HID interface. + + Submit a USB set HID protocol request for the USB device specified by UsbIo + and Interface and set the protocol to the value specified by Protocol. + If UsbIo is NULL, then ASSERT(). - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set protocol. - @param Protocol Protocol value the caller wants to set. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param Protocol The protocol value to set for the specified USB target. - @return Status of setting Protocol Request through USB I/O - protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -106,15 +133,20 @@ UsbSetProtocolRequest ( ); /** - Set Idel request. + Set the idle rate of the specified USB HID report. + + Submit a USB set HID report idle request for the USB device specified by UsbIo, + Interface, and ReportId, and set the idle rate to the value specified by Duration. + If UsbIo is NULL, then ASSERT(). - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set. - @param ReportId Which report the caller wants to set. - @param Duration Idle rate the caller wants to set. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param Duration The idle rate to set for the specified USB target. - @return Status of setting IDLE Request through USB I/O - protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -127,15 +159,21 @@ UsbSetIdleRequest ( ); /** - Get Idel request. + Get the idle rate of the specified USB HID report. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to get. - @param ReportId Which report the caller wants to get. - @param Duration Idle rate the caller wants to get. + Submit a USB get HID report idle request for the USB device specified by UsbIo, + Interface, and ReportId, and return the ide rate in Duration. + If UsbIo is NULL, then ASSERT(). + If Duration is NULL, then ASSERT(). - @return Status of getting IDLE Request through USB I/O - protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param Duration A pointer to the idle rate retrieved from the specified USB target. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -148,17 +186,18 @@ UsbGetIdleRequest ( ); /** - Hid Set Report request. + Set the report descriptor of the specified USB HID interface. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set. - @param ReportId Which report the caller wants to set. - @param ReportType Type of report. - @param ReportLen Length of report descriptor. - @param Report Report Descriptor buffer. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param ReportType The type of report to retrieve. + @param ReportLength The size, in bytes, of Report. + @param Report A pointer to the report descriptor buffer to set. - @return Status of setting Report Request through USB I/O - protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -173,17 +212,27 @@ UsbSetReportRequest ( ); /** - Hid Set Report request. - - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set. - @param ReportId Which report the caller wants to set. - @param ReportType Type of report. - @param ReportLen Length of report descriptor. - @param Report Caller allocated buffer to store Report Descriptor. - - @return Status of getting Report Request through USB I/O - protocol's UsbControlTransfer(). + Get the report descriptor of the specified USB HID interface. + + Submit a USB get HID report request for the USB device specified by UsbIo, + Interface, ReportId, and ReportType, and return the report in the buffer + specified by Report. + If UsbIo is NULL, then ASSERT(). + If Report is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param ReportType The type of report to retrieve. + @param ReportLength The size, in bytes, of Report. + @param Report A pointer to the buffer to store the report descriptor. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed because the + buffer specifed by ReportLength and Report is not + large enough to hold the result of the request. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -198,18 +247,29 @@ UsbGetReportRequest ( ); /** - Usb Get Descriptor. - - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Value Device Request Value. - @param Index Device Request Index. - @param DescriptorLength Descriptor Length. - @param Descriptor Descriptor buffer to contain result. - @param Status Transfer Status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Get the descriptor of the specified USB device. + + Submit a USB get descriptor request for the USB device specified by UsbIo, Value, + and Index, and return the descriptor in the buffer specified by Descriptor. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Descriptor is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Value The device request value. + @param Index The device request index. + @param DescriptorLength The size, in bytes, of Descriptor. + @param Descriptor A pointer to the descriptor buffer to get. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed because the + buffer specifed by DescriptorLength and Descriptor + is not large enough to hold the result of the request. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. The transfer + status is returned in Status. **/ EFI_STATUS @@ -224,18 +284,26 @@ UsbGetDescriptor ( ); /** - Usb Set Descriptor. - - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Value Device Request Value. - @param Index Device Request Index. - @param DescriptorLength Descriptor Length. - @param Descriptor Descriptor buffer to set. - @param Status Transfer Status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Set the descriptor of the specified USB device. + + Submit a USB set descriptor request for the USB device specified by UsbIo, + Value, and Index, and set the descriptor using the buffer specified by DesriptorLength + and Descriptor. The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Descriptor is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Value The device request value. + @param Index The device request index. + @param DescriptorLength The size, in bytes, of Descriptor. + @param Descriptor A pointer to the descriptor buffer to set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS @@ -250,178 +318,245 @@ UsbSetDescriptor ( ); /** - Usb Get Device Interface. + Get the interface setting of the specified USB device. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Index Interface index value. - @param AltSetting Alternate setting. - @param Status Trasnsfer status. + Submit a USB get interface request for the USB device specified by UsbIo, + and Interface, and place the result in the buffer specified by AlternateSetting. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If AlternateSetting is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The interface index value. + @param AlternateSetting A pointer to the alternate setting to be retrieved. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbGetInterface ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT16 Index, - OUT UINT8 *AltSetting, + IN UINT16 Interface, + OUT UINT8 *AlternateSetting, OUT UINT32 *Status ); /** - Usb Set Device Interface. + Set the interface setting of the specified USB device. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param InterfaceNo Interface Number. - @param AltSetting Alternate setting. - @param Status Trasnsfer status. + Submit a USB set interface request for the USB device specified by UsbIo, and + Interface, and set the alternate setting to the value specified by AlternateSetting. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The interface index value. + @param AlternateSetting The alternate setting to be set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_SUCCESS The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbSetInterface ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT16 InterfaceNo, - IN UINT16 AltSetting, + IN UINT16 Interface, + IN UINT16 AlternateSetting, OUT UINT32 *Status ); /** - Usb Get Device Configuration. + Get the device configuration. + + Submit a USB get configuration request for the USB device specified by UsbIo + and place the result in the buffer specified by ConfigurationValue. The status + of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If ConfigurationValue is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param ConfigValue Config Value. - @param Status Transfer Status. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param ConfigurationValue A pointer to the device configuration to be retrieved. + @param Status A pointer to the status of the transfer. - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbGetConfiguration ( IN EFI_USB_IO_PROTOCOL *UsbIo, - OUT UINT8 *ConfigValue, + OUT UINT8 *ConfigurationValue, OUT UINT32 *Status ); /** - Usb Set Device Configuration. + Set the device configuration. - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Value Configuration Value to set. - @param Status Transfer status. + Submit a USB set configuration request for the USB device specified by UsbIo + and set the device configuration to the value specified by ConfigurationValue. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param ConfigurationValue The device configuration value to be set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbSetConfiguration ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT16 Value, + IN UINT16 ConfigurationValue, OUT UINT32 *Status ); /** - Usb Set Device Feature. - - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Recipient Interface/Device/Endpoint. - @param Value Request value. - @param Target Request Index. - @param Status Transfer status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Set the specified feature of the specified device. + + Submit a USB set device feature request for the USB device specified by UsbIo, + Recipient, and Target to the value specified by Value. The status of the + transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). + Type USB_TYPES_DEFINITION is defined in the MDE Package Industry + Standard include file Usb.h. + @param Value The value of the feature to be set. + @param Target The index of the device to be set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbSetFeature ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINTN Recipient, + IN USB_TYPES_DEFINITION Recipient, IN UINT16 Value, IN UINT16 Target, OUT UINT32 *Status ); /** - Usb Clear Device Feature. - - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Recipient Interface/Device/Endpoint. - @param Value Request value. - @param Target Request Index. - @param Status Transfer status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Clear the specified feature of the specified device. + + Submit a USB clear device feature request for the USB device specified by UsbIo, + Recipient, and Target to the value specified by Value. The status of the transfer + is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). + Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard + include file Usb.h. + @param Value The value of the feature to be cleared. + @param Target The index of the device to be cleared. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbClearFeature ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINTN Recipient, + IN USB_TYPES_DEFINITION Recipient, IN UINT16 Value, IN UINT16 Target, OUT UINT32 *Status ); /** - Usb Get Device Status. - - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param Recipient Interface/Device/Endpoint. - @param Target Request index. - @param DevStatus Device status. - @param Status Transfer status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Get the status of the specified device. + + Submit a USB device get status request for the USB device specified by UsbIo, + Recipient, and Target and place the result in the buffer specified by DeviceStatus. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If DeviceStatus is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). + Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard + include file Usb.h. + @param Target The index of the device to be get the status of. + @param DeviceStatus A pointer to the device status to be retrieved. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbGetStatus ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINTN Recipient, + IN USB_TYPES_DEFINITION Recipient, IN UINT16 Target, OUT UINT16 *DevStatus, OUT UINT32 *Status ); /** - Clear endpoint stall. + Clear halt feature of the specified usb endpoint. + + Retrieve the USB endpoint descriptor specified by UsbIo and EndPoint. + If the USB endpoint descriptor can not be retrieved, then return EFI_NOT_FOUND. + If the endpoint descriptor is found, then clear the halt fature of this USB endpoint. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @param UsbIo A pointer to EFI_USB_IO_PROTOCOL. - @param EndpointNo Endpoint Number. - @param Status Transfer Status. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Endpoint The endpoint address. + @param Status A pointer to the status of the transfer. - @retval EFI_NOT_FOUND Can't find the Endpoint. - @retval EFI_DEVICE_ERROR Hardware error. - @retval EFI_SUCCESS Success. + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. + @retval EFI_NOT_FOUND The specified USB endpoint descriptor can not be found **/ EFI_STATUS EFIAPI UsbClearEndpointHalt ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 EndpointNo, + IN UINT8 Endpoint, OUT UINT32 *Status ); diff --git a/MdePkg/Library/UefiScsiLib/UefiScsiLib.c b/MdePkg/Library/UefiScsiLib/UefiScsiLib.c index a90a37b74d..3b4da1fb0e 100644 --- a/MdePkg/Library/UefiScsiLib/UefiScsiLib.c +++ b/MdePkg/Library/UefiScsiLib/UefiScsiLib.c @@ -17,72 +17,105 @@ #include #include #include - + #include - -// -// Max bytes needed to represent ID of a SCSI device -// + + + // + // Max bytes needed to represent ID of a SCSI device + // #define EFI_SCSI_TARGET_MAX_BYTES (0x10) - -// -// bit5..7 are for Logical unit number -// 11100000b (0xe0) -// + + // + // bit5..7 are for Logical unit number + // 11100000b (0xe0) + // #define EFI_SCSI_LOGICAL_UNIT_NUMBER_MASK 0xe0 - -// -// Scsi Command Length six or ten -// + + // + // Scsi Command Length six or ten + // #define EFI_SCSI_OP_LENGTH_SIX 0x6 #define EFI_SCSI_OP_LENGTH_TEN 0xa -/** - 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(). +/** + Execute Test Unit Ready SCSI command on a specific SCSI target. + Executes the Test Unit Ready command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). + 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[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 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 the SCSI I/O Protocol instance + for the specific SCSI target. + @param[in] Timeout The timeout in 100 ns units to use for the execution + of this SCSI Request Packet. A Timeout value of + zero means that this function will wait indefinitely + for the SCSI Request Packet to execute. If Timeout + is greater than zero, then this function will return + EFI_TIMEOUT if the time required to execute the SCSI + Request Packet is greater than Timeout. + @param[in, out] SenseData A pointer to sense data that was generated by + the execution of the SCSI Request Packet. This + buffer must be allocated by the caller. + If SenseDataLength is 0, then this parameter is + optional and may be NULL. + @param[in, out] SenseDataLength On input, a pointer to the length in bytes of + the SenseData buffer. On output, a poiinter to + the number of bytes written to the SenseData buffer. + @param[out] HostAdapterStatus The status of the SCSI Host Controller that produces + the SCSI bus containing the SCSI target specified by + ScsiIo when the SCSI Request Packet was executed. + See the EFI SCSI I/O Protocol in the UEFI Specification + for details on the possible return values. + @param[out] TargetStatus The status returned by the SCSI target specified + by ScsiIo when the SCSI Request Packat was executed + on the SCSI Host Controller. See the EFI SCSI I/O + Protocol in the UEFI Specification for details on + the possible return values. + + @retval EFI_SUCCESS The command was executed successfully. + See HostAdapterStatus, TargetStatus, SenseDataLength, + and SenseData in that order for additional status + information. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because + there are too many SCSI Command Packets already + queued. The SCSI Request Packet was not sent, so + no additional status information is available. + The caller may retry again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send + SCSI Request Packet. See HostAdapterStatus, + TargetStatus, SenseDataLength, and SenseData in that + order for additional status information. + @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet + is not supported by the SCSI initiator(i.e., SCSI + Host Controller). The SCSI Request Packet was not + sent, so no additional status information is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request + Packet to execute. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for + additional status information. + @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. **/ EFI_STATUS EFIAPI ScsiTestUnitReadyCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -95,10 +128,7 @@ ScsiTestUnitReadyCommand ( ASSERT (SenseDataLength != NULL); ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_SIX); @@ -132,59 +162,95 @@ 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. + Execute Inquiry SCSI command on a specific SCSI target. + Executes the Inquiry command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). 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 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 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. + @param[in] ScsiIo A pointer to the SCSI I/O Protocol instance + for the specific SCSI target. + @param[in] Timeout The timeout in 100 ns units to use for the + execution of this SCSI Request Packet. A Timeout + value of zero means that this function will wait + indefinitely for the SCSI Request Packet to execute. + If Timeout is greater than zero, then this function + will return EFI_TIMEOUT if the time required to + execute the SCSI Request Packet is greater than Timeout. + @param[in, out] SenseData A pointer to sense data that was generated + by the execution of the SCSI Request Packet. + This buffer must be allocated by the caller. + If SenseDataLength is 0, then this parameter + is optional and may be NULL. + @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 the SCSI Host Controller that + produces the SCSI bus containing the SCSI + target specified by ScsiIo when the SCSI + Request Packet was executed. See the EFI + SCSI I/O Protocol in the UEFI Specification + for details on the possible return values. + @param[out] TargetStatus The status returned by the SCSI target specified + by ScsiIo when the SCSI Request Packat was + executed on the SCSI Host Controller. + See the EFI SCSI I/O Protocol in the UEFI + Specification for details on the possible + return values. + @param[in, out] InquiryDataBuffer A pointer to inquiry data that was generated + by the execution of the SCSI Request Packet. + This buffer must be allocated by the caller. + If InquiryDataLength is 0, then this parameter + is optional and may be NULL. + @param[in, out] InquiryDataLength On input, a pointer to the length in bytes + of the InquiryDataBuffer buffer. + On output, a pointer to the number of bytes + written to the InquiryDataBuffer buffer. + @param[in] EnableVitalProductData If TRUE, then the supported vital product + data is returned in InquiryDataBuffer. + If FALSE, then the standard inquiry data is + returned in InquiryDataBuffer. + + @retval EFI_SUCCESS The command was executed successfully. See HostAdapterStatus, + TargetStatus, SenseDataLength, and SenseData in that order + for additional status information. + @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, but the entire + InquiryDataBuffer could not be transferred. The actual + number of bytes transferred is returned in InquiryDataLength. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because there + are too many SCSI Command Packets already queued. + The SCSI Request Packet was not sent, so no additional + status information is available. The caller may retry again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send SCSI + Request Packet. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for additional + status information. + @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet is not + supported by the SCSI initiator(i.e., SCSI Host Controller). + The SCSI Request Packet was not sent, so no additional + status information is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request + Packet to execute. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for + additional status information. **/ EFI_STATUS EFIAPI ScsiInquiryCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - IN OUT VOID *InquiryDataBuffer, - IN OUT UINT32 *InquiryDataLength, - IN BOOLEAN EnableVitalProductData + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *InquiryDataBuffer, OPTIONAL + IN OUT UINT32 *InquiryDataLength, + IN BOOLEAN EnableVitalProductData ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -198,10 +264,7 @@ ScsiInquiryCommand ( ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); ASSERT (InquiryDataLength != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_SIX); @@ -242,63 +305,100 @@ 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. - + Execute Mode Sense(10) SCSI command on a specific SCSI target. + + Executes the SCSI Mode Sense(10) command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout + after Timeout 100 ns units. The DBDField, PageControl, and PageCode parameters + are used to construct the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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 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_BAD_BUFFER_SIZE The SCSI Request Packet was executed, - but the entire DataBuffer could not be transferred. + + @param[in] ScsiIo A pointer to the SCSI I/O Protocol instance + for the specific SCSI target. + @param[in] Timeout The timeout in 100 ns units to use for the + execution of this SCSI Request Packet. A Timeout + value of zero means that this function will wait + indefinitely for the SCSI Request Packet to execute. + If Timeout is greater than zero, then this function + will return EFI_TIMEOUT if the time required to + execute the SCSI Request Packet is greater than Timeout. + @param[in, out] SenseData A pointer to sense data that was generated + by the execution of the SCSI Request Packet. + This buffer must be allocated by the caller. + If SenseDataLength is 0, then this parameter + is optional and may be NULL. + @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 the SCSI Host Controller that + produces the SCSI bus containing the SCSI target + specified by ScsiIo when the SCSI Request Packet + was executed. See the EFI SCSI I/O Protocol in the + UEFI Specification for details on the possible + return values. + @param[out] TargetStatus The status returned by the SCSI target specified + by ScsiIo when the SCSI Request Packat was executed + on the SCSI Host Controller. See the EFI SCSI + I/O Protocol in the UEFI Specification for details + on the possible return values. + @param[in, out] DataBuffer A pointer to data that was generated by the + execution of the SCSI Request Packet. This + buffer must be allocated by the caller. If + DataLength is 0, then this parameter is optional + and may be NULL. + @param[in, out] DataLength On input, a pointer to the length in bytes of + the DataBuffer buffer. On output, a pointer + to the number of bytes written to the DataBuffer + buffer. + @param[in] DBDField Specifies the DBD field of the CDB for this SCSI Command. + @param[in] PageControl Specifies the PC field of the CDB for this SCSI Command. + @param[in] PageCode Specifies the Page Control field of the CDB for this SCSI Command. + + @retval EFI_SUCCESS The command was executed successfully. + See HostAdapterStatus, TargetStatus, SenseDataLength, + and SenseData in that order for additional status information. + @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. + in DataLength. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because + there are too many SCSI Command Packets already queued. + The SCSI Request Packet was not sent, so no additional + status information is available. The caller may retry + again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send + SCSI Request Packet. See HostAdapterStatus, TargetStatus, + SenseDataLength, and SenseData in that order for + additional status information. @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. + is not supported by the SCSI initiator(i.e., SCSI + Host Controller). The SCSI Request Packet was not + sent, so no additional status information is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI + Request Packet to execute. See HostAdapterStatus, + TargetStatus, SenseDataLength, and SenseData in that + order for additional status information. **/ EFI_STATUS EFIAPI ScsiModeSense10Command ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - IN VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN UINT8 DBDField, OPTIONAL - IN UINT8 PageControl, - IN UINT8 PageCode + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN UINT8 DBDField, OPTIONAL + IN UINT8 PageControl, + IN UINT8 PageCode ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -312,10 +412,7 @@ ScsiModeSense10Command ( ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); ASSERT (DataLength != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_TEN); @@ -359,21 +456,20 @@ 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. + Execute Request Sense SCSI command on a specific SCSI target. + Executes the Request Sense command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). 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 The length of output sense data. + @param[in, 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. @@ -384,18 +480,17 @@ ScsiModeSense10Command ( @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 EFIAPI ScsiRequestSenseCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -408,10 +503,7 @@ ScsiRequestSenseCommand ( ASSERT (SenseDataLength != NULL); ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_SIX); @@ -446,28 +538,27 @@ 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. + Execute Read Capacity SCSI command on a specific SCSI target. + Executes the SCSI Read Capacity command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after + Timeout 100 ns units. The PMI parameter is used to construct the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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] ScsiIo A pointer to SCSI IO protocol. + @param[in] Timeout The length of timeout period. + @param[in, 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[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in, out] DataBuffer A pointer to a data buffer. @param[in, out] DataLength The length of data buffer. - @param[in] PMI Partial medium indicator. + @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 @@ -478,21 +569,20 @@ ScsiRequestSenseCommand ( @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 EFIAPI ScsiReadCapacityCommand ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - OUT VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN BOOLEAN PMI + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN BOOLEAN PMI ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -506,10 +596,7 @@ ScsiReadCapacityCommand ( ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); ASSERT (DataLength != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_TEN); @@ -552,29 +639,30 @@ 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. - + Execute Read(10) SCSI command on a specific SCSI target. + + Executes the SCSI Read(10) command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout + after Timeout 100 ns units. The StartLba and SectorSize parameters are used to + construct the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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] ScsiIo A pointer to SCSI IO protocol. + @param[in] Timeout The length of timeout period. + @param[in, 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[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in, 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. + @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 @@ -585,22 +673,21 @@ ScsiReadCapacityCommand ( @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 EFIAPI ScsiRead10Command ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - OUT VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN UINT32 StartLba, - IN UINT32 SectorSize + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN UINT32 StartLba, + IN UINT32 SectorSize ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -614,10 +701,7 @@ ScsiRead10Command ( ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); ASSERT (DataLength != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_TEN); @@ -658,29 +742,29 @@ 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. - + Execute Write(10) SCSI command on a specific SCSI target. + + Executes the SCSI Write(10) command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after + Timeout 100 ns units. The StartLba and SectorSize parameters are used to construct + the CDB for this SCSI command. + If ScsiIo is NULL, then ASSERT(). 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 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. + @param[in] ScsiIo SCSI IO Protocol to use + @param[in] Timeout The length of timeout period. + @param[in, 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] 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 @@ -691,22 +775,21 @@ ScsiRead10Command ( @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 EFIAPI ScsiWrite10Command ( - IN EFI_SCSI_IO_PROTOCOL *ScsiIo, - IN UINT64 Timeout, - IN VOID *SenseData, - IN OUT UINT8 *SenseDataLength, - OUT UINT8 *HostAdapterStatus, - OUT UINT8 *TargetStatus, - OUT VOID *DataBuffer, - IN OUT UINT32 *DataLength, - IN UINT32 StartLba, - IN UINT32 SectorSize + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN OUT VOID *DataBuffer, OPTIONAL + IN OUT UINT32 *DataLength, + IN UINT32 StartLba, + IN UINT32 SectorSize ) { EFI_SCSI_IO_SCSI_REQUEST_PACKET CommandPacket; @@ -720,10 +803,7 @@ ScsiWrite10Command ( ASSERT (HostAdapterStatus != NULL); ASSERT (TargetStatus != NULL); ASSERT (DataLength != NULL); - - if (ScsiIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (ScsiIo != NULL); ZeroMem (&CommandPacket, sizeof (EFI_SCSI_IO_SCSI_REQUEST_PACKET)); ZeroMem (Cdb, EFI_SCSI_OP_LENGTH_TEN); diff --git a/MdePkg/Library/UefiUsbLib/Hid.c b/MdePkg/Library/UefiUsbLib/Hid.c index 0e9be35206..d2a4b577ff 100644 --- a/MdePkg/Library/UefiUsbLib/Hid.c +++ b/MdePkg/Library/UefiUsbLib/Hid.c @@ -30,37 +30,43 @@ // /** - Get Hid Descriptor. + Get the descriptor of the specified USB HID interface. - @param UsbIo EFI_USB_IO_PROTOCOL. - @param InterfaceNum Hid interface number. - @param HidDescriptor Caller allocated buffer to store Usb hid descriptor if - successfully returned. + Submit a USB get HID descriptor request for the USB device specified by UsbIo + and Interface and return the HID descriptor in HidDescriptor. + If UsbIo is NULL, then ASSERT(). + If HidDescriptor is NULL, then ASSERT(). - @return Status of getting HID descriptor through USB I/O - protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the HID interface on the USB target. + @param HidDescriptor Pointer to the USB HID descriptor that was retrieved from + the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR + is defined in the MDE Package Industry Standard include file Usb.h. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS EFIAPI UsbGetHidDescriptor ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 InterfaceNum, + IN UINT8 Interface, OUT EFI_USB_HID_DESCRIPTOR *HidDescriptor ) { UINT32 Status; EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + + ASSERT(UsbIo != NULL); + ASSERT(HidDescriptor != NULL); Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE; Request.Request = USB_REQ_GET_DESCRIPTOR; Request.Value = (UINT16) (USB_DESC_TYPE_HID << 8); - Request.Index = InterfaceNum; + Request.Index = Interface; Request.Length = sizeof (EFI_USB_HID_DESCRIPTOR); Result = UsbIo->UsbControlTransfer ( @@ -78,24 +84,32 @@ UsbGetHidDescriptor ( } /** - Get Report Class descriptor. + Get the report descriptor of the specified USB HID interface. - @param UsbIo EFI_USB_IO_PROTOCOL. - @param InterfaceNum Report interface number. - @param DescriptorSize Length of DescriptorBuffer. - @param DescriptorBuffer Caller allocated buffer to store Usb report descriptor - if successfully returned. + Submit a USB get HID report descriptor request for the USB device specified by + UsbIo and Interface and return the report descriptor in DescriptorBuffer. + If UsbIo is NULL, then ASSERT(). + If DescriptorBuffer is NULL, then ASSERT(). - @return Status of getting Report Class descriptor through USB - I/O protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param DescriptorLength The size, in bytes, of DescriptorBuffer. + @param DescriptorBuffer A pointer to the buffer to store the report class descriptor. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed because the + buffer specifed by DescriptorLength and DescriptorBuffer + is not large enough to hold the result of the request. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS EFIAPI UsbGetReportDescriptor ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 InterfaceNum, - IN UINT16 DescriptorSize, + IN UINT8 Interface, + IN UINT16 DescriptorLength, OUT UINT8 *DescriptorBuffer ) { @@ -103,17 +117,17 @@ UsbGetReportDescriptor ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (DescriptorBuffer != NULL); + // // Fill Device request packet // Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE; Request.Request = USB_REQ_GET_DESCRIPTOR; Request.Value = (UINT16) (USB_DESC_TYPE_REPORT << 8); - Request.Index = InterfaceNum; - Request.Length = DescriptorSize; + Request.Index = Interface; + Request.Length = DescriptorLength; Result = UsbIo->UsbControlTransfer ( UsbIo, @@ -121,7 +135,7 @@ UsbGetReportDescriptor ( EfiUsbDataIn, TIMEOUT_VALUE, DescriptorBuffer, - DescriptorSize, + DescriptorLength, &Status ); @@ -130,14 +144,20 @@ UsbGetReportDescriptor ( } /** - Get Hid Protocol Request + Get the HID protocol of the specified USB HID interface. + + Submit a USB get HID protocol request for the USB device specified by UsbIo + and Interface and return the protocol retrieved in Protocol. + If UsbIo is NULL, then ASSERT(). + If Protocol is NULL, then ASSERT(). - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to get protocol - @param Protocol Protocol value returned. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param Protocol A pointer to the protocol for the specified USB target. - @return Status of getting Protocol Request through USB I/O - protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -152,9 +172,9 @@ UsbGetProtocolRequest ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Protocol != NULL); + // // Fill Device request packet // @@ -180,15 +200,19 @@ UsbGetProtocolRequest ( /** - Set Hid Protocol Request. + Set the HID protocol of the specified USB HID interface. - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to - set protocol. - @param Protocol Protocol value the caller wants to set. + Submit a USB set HID protocol request for the USB device specified by UsbIo + and Interface and set the protocol to the value specified by Protocol. + If UsbIo is NULL, then ASSERT(). - @return Status of setting Protocol Request through USB I/O - protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param Protocol The protocol value to set for the specified USB target. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -203,9 +227,8 @@ UsbSetProtocolRequest ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + // // Fill Device request packet // @@ -229,15 +252,20 @@ UsbSetProtocolRequest ( /** - Set Idel request. + Set the idle rate of the specified USB HID report. - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set. - @param ReportId Which report the caller wants to set. - @param Duration Idle rate the caller wants to set. + Submit a USB set HID report idle request for the USB device specified by UsbIo, + Interface, and ReportId, and set the idle rate to the value specified by Duration. + If UsbIo is NULL, then ASSERT(). - @return Status of setting IDLE Request through USB I/O - protocol's UsbControlTransfer(). + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param Duration The idle rate to set for the specified USB target. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -253,9 +281,7 @@ UsbSetIdleRequest ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); // // Fill Device request packet // @@ -279,15 +305,21 @@ UsbSetIdleRequest ( /** - Get Idel request. + Get the idle rate of the specified USB HID report. + + Submit a USB get HID report idle request for the USB device specified by UsbIo, + Interface, and ReportId, and return the ide rate in Duration. + If UsbIo is NULL, then ASSERT(). + If Duration is NULL, then ASSERT(). - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to get. - @param ReportId Which report the caller wants to get. - @param Duration Idle rate the caller wants to get. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param Duration A pointer to the idle rate retrieved from the specified USB target. - @return Status of getting IDLE Request through USB I/O - protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -303,9 +335,8 @@ UsbGetIdleRequest ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Duration != NULL); // // Fill Device request packet // @@ -331,17 +362,24 @@ UsbGetIdleRequest ( /** - Hid Set Report request. + Set the report descriptor of the specified USB HID interface. + + Submit a USB set HID report request for the USB device specified by UsbIo, + Interface, ReportId, and ReportType, and set the report descriptor using the + buffer specified by ReportLength and Report. + If UsbIo is NULL, then ASSERT(). + If Report is NULL, then ASSERT(). - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set. - @param ReportId Which report the caller wants to set. - @param ReportType Type of report. - @param ReportLen Length of report descriptor. - @param Report Report Descriptor buffer. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param ReportType The type of report to retrieve. + @param ReportLength The size, in bytes, of Report. + @param Report A pointer to the report descriptor buffer to set. - @return Status of setting Report Request through USB I/O - protocol's UsbControlTransfer(). + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -351,7 +389,7 @@ UsbSetReportRequest ( IN UINT8 Interface, IN UINT8 ReportId, IN UINT8 ReportType, - IN UINT16 ReportLen, + IN UINT16 ReportLength, IN UINT8 *Report ) { @@ -359,9 +397,9 @@ UsbSetReportRequest ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Report != NULL); + // // Fill Device request packet // @@ -369,7 +407,7 @@ UsbSetReportRequest ( Request.Request = EFI_USB_SET_REPORT_REQUEST; Request.Value = (UINT16) ((ReportType << 8) | ReportId); Request.Index = Interface; - Request.Length = ReportLen; + Request.Length = ReportLength; Result = UsbIo->UsbControlTransfer ( UsbIo, @@ -377,7 +415,7 @@ UsbSetReportRequest ( EfiUsbDataOut, TIMEOUT_VALUE, Report, - ReportLen, + ReportLength, &Status ); @@ -386,17 +424,27 @@ UsbSetReportRequest ( /** - Hid Set Report request. - - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Interface Which interface the caller wants to set. - @param ReportId Which report the caller wants to set. - @param ReportType Type of report. - @param ReportLen Length of report descriptor. - @param Report Caller allocated buffer to store Report Descriptor. - - @return Status of getting Report Request through USB I/O - protocol's UsbControlTransfer(). + Get the report descriptor of the specified USB HID interface. + + Submit a USB get HID report request for the USB device specified by UsbIo, + Interface, ReportId, and ReportType, and return the report in the buffer + specified by Report. + If UsbIo is NULL, then ASSERT(). + If Report is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The index of the report interface on the USB target. + @param ReportId The identifier of the report to retrieve. + @param ReportType The type of report to retrieve. + @param ReportLength The size, in bytes, of Report. + @param Report A pointer to the buffer to store the report descriptor. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed because the + buffer specifed by ReportLength and Report is not + large enough to hold the result of the request. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. **/ EFI_STATUS @@ -414,9 +462,9 @@ UsbGetReportRequest ( EFI_STATUS Result; EFI_USB_DEVICE_REQUEST Request; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Report != NULL); + // // Fill Device request packet // diff --git a/MdePkg/Library/UefiUsbLib/UefiUsbLib.inf b/MdePkg/Library/UefiUsbLib/UefiUsbLib.inf index 12290dc571..6ebd81a426 100644 --- a/MdePkg/Library/UefiUsbLib/UefiUsbLib.inf +++ b/MdePkg/Library/UefiUsbLib/UefiUsbLib.inf @@ -38,5 +38,6 @@ MdePkg/MdePkg.dec [LibraryClasses] + DebugLib BaseMemoryLib diff --git a/MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h b/MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h index e8c817ae1d..329606d565 100644 --- a/MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h +++ b/MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h @@ -13,11 +13,16 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ -#ifndef __UEFI_USB_LIB_INTERNAL_H_ -#define __UEFI_USB_LIB_INTERNAL_H_ +#ifndef _UEFI_USB_LIB_INTERNAL_H_ +#define _UEFI_USB_LIB_INTERNAL_H_ #include + #include #include +#include + +#include + #endif diff --git a/MdePkg/Library/UefiUsbLib/UsbDxeLib.c b/MdePkg/Library/UefiUsbLib/UsbDxeLib.c index 18fe37c381..a15ef6ebef 100644 --- a/MdePkg/Library/UefiUsbLib/UsbDxeLib.c +++ b/MdePkg/Library/UefiUsbLib/UsbDxeLib.c @@ -19,18 +19,29 @@ /** - Usb Get Descriptor. - - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Value Device Request Value. - @param Index Device Request Index. - @param DescriptorLength Descriptor Length. - @param Descriptor Descriptor buffer to contain result. - @param Status Transfer Status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Get the descriptor of the specified USB device. + + Submit a USB get descriptor request for the USB device specified by UsbIo, Value, + and Index, and return the descriptor in the buffer specified by Descriptor. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Descriptor is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Value The device request value. + @param Index The device request index. + @param DescriptorLength The size, in bytes, of Descriptor. + @param Descriptor A pointer to the descriptor buffer to get. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_OUT_OF_RESOURCES The request could not be completed because the + buffer specifed by DescriptorLength and Descriptor + is not large enough to hold the result of the request. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. The transfer + status is returned in Status. **/ EFI_STATUS @@ -46,9 +57,9 @@ UsbGetDescriptor ( { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Descriptor != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); @@ -71,18 +82,26 @@ UsbGetDescriptor ( /** - Usb Set Descriptor. - - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Value Device Request Value. - @param Index Device Request Index. - @param DescriptorLength Descriptor Length. - @param Descriptor Descriptor buffer to set. - @param Status Transfer Status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Set the descriptor of the specified USB device. + + Submit a USB set descriptor request for the USB device specified by UsbIo, + Value, and Index, and set the descriptor using the buffer specified by DesriptorLength + and Descriptor. The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Descriptor is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Value The device request value. + @param Index The device request index. + @param DescriptorLength The size, in bytes, of Descriptor. + @param Descriptor A pointer to the descriptor buffer to set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS @@ -98,9 +117,9 @@ UsbSetDescriptor ( { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Descriptor != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); @@ -123,38 +142,46 @@ UsbSetDescriptor ( /** - Usb Get Device Interface. + Get the interface setting of the specified USB device. - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Index Interface index value. - @param AltSetting Alternate setting. - @param Status Trasnsfer status. + Submit a USB get interface request for the USB device specified by UsbIo, + and Interface, and place the result in the buffer specified by AlternateSetting. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If AlternateSetting is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The interface index value. + @param AlternateSetting A pointer to the alternate setting to be retrieved. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbGetInterface ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT16 Index, - OUT UINT8 *AltSetting, + IN UINT16 Interface, + OUT UINT8 *AlternateSetting, OUT UINT32 *Status ) { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (AlternateSetting != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); DevReq.RequestType = USB_DEV_GET_INTERFACE_REQ_TYPE; DevReq.Request = USB_REQ_GET_INTERFACE; - DevReq.Index = Index; + DevReq.Index = Interface; DevReq.Length = 1; return UsbIo->UsbControlTransfer ( @@ -162,7 +189,7 @@ UsbGetInterface ( &DevReq, EfiUsbDataIn, TIMEOUT_VALUE, - AltSetting, + AlternateSetting, 1, Status ); @@ -170,40 +197,45 @@ UsbGetInterface ( /** - Usb Set Device Interface. + Set the interface setting of the specified USB device. - @param UsbIo EFI_USB_IO_PROTOCOL. - @param InterfaceNo Interface Number. - @param AltSetting Alternate setting. - @param Status Trasnsfer status. + Submit a USB set interface request for the USB device specified by UsbIo, and + Interface, and set the alternate setting to the value specified by AlternateSetting. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Interface The interface index value. + @param AlternateSetting The alternate setting to be set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_SUCCESS The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbSetInterface ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT16 InterfaceNo, - IN UINT16 AltSetting, + IN UINT16 Interface, + IN UINT16 AlternateSetting, OUT UINT32 *Status ) { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); DevReq.RequestType = USB_DEV_SET_INTERFACE_REQ_TYPE; DevReq.Request = USB_REQ_SET_INTERFACE; - DevReq.Value = AltSetting; - DevReq.Index = InterfaceNo; - + DevReq.Value = AlternateSetting; + DevReq.Index = Interface; return UsbIo->UsbControlTransfer ( UsbIo, @@ -218,30 +250,38 @@ UsbSetInterface ( /** - Usb Get Device Configuration. + Get the device configuration. + + Submit a USB get configuration request for the USB device specified by UsbIo + and place the result in the buffer specified by ConfigurationValue. The status + of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If ConfigurationValue is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @param UsbIo EFI_USB_IO_PROTOCOL. - @param ConfigValue Config Value. - @param Status Transfer Status. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param ConfigurationValue A pointer to the device configuration to be retrieved. + @param Status A pointer to the status of the transfer. - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbGetConfiguration ( IN EFI_USB_IO_PROTOCOL *UsbIo, - OUT UINT8 *ConfigValue, + OUT UINT8 *ConfigurationValue, OUT UINT32 *Status ) { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (ConfigurationValue != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); @@ -254,7 +294,7 @@ UsbGetConfiguration ( &DevReq, EfiUsbDataIn, TIMEOUT_VALUE, - ConfigValue, + ConfigurationValue, 1, Status ); @@ -262,36 +302,42 @@ UsbGetConfiguration ( /** - Usb Set Device Configuration. + Set the device configuration. + + Submit a USB set configuration request for the USB device specified by UsbIo + and set the device configuration to the value specified by ConfigurationValue. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Value Configuration Value to set. - @param Status Transfer status. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param ConfigurationValue The device configuration value to be set. + @param Status A pointer to the status of the transfer. - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbSetConfiguration ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT16 Value, + IN UINT16 ConfigurationValue, OUT UINT32 *Status ) { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); DevReq.RequestType = USB_DEV_SET_CONFIGURATION_REQ_TYPE; DevReq.Request = USB_REQ_SET_CONFIG; - DevReq.Value = Value; + DevReq.Value = ConfigurationValue; return UsbIo->UsbControlTransfer ( UsbIo, @@ -306,24 +352,33 @@ UsbSetConfiguration ( /** - Usb Set Device Feature. - - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Recipient Interface/Device/Endpoint. - @param Value Request value. - @param Target Request Index. - @param Status Transfer status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Set the specified feature of the specified device. + + Submit a USB set device feature request for the USB device specified by UsbIo, + Recipient, and Target to the value specified by Value. The status of the + transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). + Type USB_TYPES_DEFINITION is defined in the MDE Package Industry + Standard include file Usb.h. + @param Value The value of the feature to be set. + @param Target The index of the device to be set. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbSetFeature ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINTN Recipient, + IN USB_TYPES_DEFINITION Recipient, IN UINT16 Value, IN UINT16 Target, OUT UINT32 *Status @@ -331,9 +386,8 @@ UsbSetFeature ( { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); @@ -372,24 +426,33 @@ UsbSetFeature ( /** - Usb Clear Device Feature. - - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Recipient Interface/Device/Endpoint. - @param Value Request value. - @param Target Request Index. - @param Status Transfer status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Clear the specified feature of the specified device. + + Submit a USB clear device feature request for the USB device specified by UsbIo, + Recipient, and Target to the value specified by Value. The status of the transfer + is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). + Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard + include file Usb.h. + @param Value The value of the feature to be cleared. + @param Target The index of the device to be cleared. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbClearFeature ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINTN Recipient, + IN USB_TYPES_DEFINITION Recipient, IN UINT16 Value, IN UINT16 Target, OUT UINT32 *Status @@ -397,9 +460,9 @@ UsbClearFeature ( { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Status != NULL); + ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); @@ -438,34 +501,44 @@ UsbClearFeature ( /** - Usb Get Device Status. - - @param UsbIo EFI_USB_IO_PROTOCOL. - @param Recipient Interface/Device/Endpoint. - @param Target Request index. - @param DevStatus Device status. - @param Status Transfer status. - - @retval EFI_INVALID_PARAMETER Parameter is error. - @retval EFI_SUCCESS Success. - @retval EFI_TIMEOUT Device has no response. + Get the status of the specified device. + + Submit a USB device get status request for the USB device specified by UsbIo, + Recipient, and Target and place the result in the buffer specified by DeviceStatus. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If DeviceStatus is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). + + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Recipient The USB data recipient type (i.e. Device, Interface, Endpoint). + Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard + include file Usb.h. + @param Target The index of the device to be get the status of. + @param DeviceStatus A pointer to the device status to be retrieved. + @param Status A pointer to the status of the transfer. + + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. **/ EFI_STATUS EFIAPI UsbGetStatus ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINTN Recipient, + IN USB_TYPES_DEFINITION Recipient, IN UINT16 Target, - OUT UINT16 *DevStatus, + OUT UINT16 *DeviceStatus, OUT UINT32 *Status ) { EFI_USB_DEVICE_REQUEST DevReq; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (DeviceStatus != NULL); + ASSERT (Status != NULL); ZeroMem (&DevReq, sizeof (EFI_USB_DEVICE_REQUEST)); @@ -496,7 +569,7 @@ UsbGetStatus ( &DevReq, EfiUsbDataIn, TIMEOUT_VALUE, - DevStatus, + DeviceStatus, 2, Status ); @@ -504,22 +577,31 @@ UsbGetStatus ( /** - Clear endpoint stall. + Clear halt feature of the specified usb endpoint. + + Retrieve the USB endpoint descriptor specified by UsbIo and EndPoint. + If the USB endpoint descriptor can not be retrieved, then return EFI_NOT_FOUND. + If the endpoint descriptor is found, then clear the halt fature of this USB endpoint. + The status of the transfer is returned in Status. + If UsbIo is NULL, then ASSERT(). + If Status is NULL, then ASSERT(). - @param UsbIo EFI_USB_IO_PROTOCOL. - @param EndpointNo Endpoint Number. - @param Status Transfer Status. + @param UsbIo A pointer to the USB I/O Protocol instance for the specific USB target. + @param Endpoint The endpoint address. + @param Status A pointer to the status of the transfer. - @retval EFI_NOT_FOUND Can't find the Endpoint. - @retval EFI_DEVICE_ERROR Hardware error. - @retval EFI_SUCCESS Success. + @retval EFI_SUCCESS The request executed successfully. + @retval EFI_TIMEOUT A timeout occurred executing the request. + @retval EFI_DEVICE_ERROR The request failed due to a device error. + The transfer status is returned in Status. + @retval EFI_NOT_FOUND The specified USB endpoint descriptor can not be found **/ EFI_STATUS EFIAPI UsbClearEndpointHalt ( IN EFI_USB_IO_PROTOCOL *UsbIo, - IN UINT8 EndpointNo, + IN UINT8 Endpoint, OUT UINT32 *Status ) { @@ -528,9 +610,8 @@ UsbClearEndpointHalt ( EFI_USB_INTERFACE_DESCRIPTOR InterfaceDescriptor; UINT8 Index; - if (UsbIo == NULL) { - return EFI_INVALID_PARAMETER; - } + ASSERT (UsbIo != NULL); + ASSERT (Status != NULL); ZeroMem (&EndpointDescriptor, sizeof (EFI_USB_ENDPOINT_DESCRIPTOR)); // @@ -554,7 +635,7 @@ UsbClearEndpointHalt ( continue; } - if (EndpointDescriptor.EndpointAddress == EndpointNo) { + if (EndpointDescriptor.EndpointAddress == Endpoint) { break; } } -- cgit v1.2.3