/** @file | |
Definition for the USB mass storage Bulk-Only Transport protocol, | |
based on the "Universal Serial Bus Mass Storage Class Bulk-Only | |
Transport" Revision 1.0, September 31, 1999. | |
Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> | |
SPDX-License-Identifier: BSD-2-Clause-Patent | |
**/ | |
#ifndef _EFI_USBMASS_BOT_H_ | |
#define _EFI_USBMASS_BOT_H_ | |
extern USB_MASS_TRANSPORT mUsbBotTransport; | |
// | |
// Usb Bulk-Only class specific request | |
// | |
#define USB_BOT_RESET_REQUEST 0xFF ///< Bulk-Only Mass Storage Reset | |
#define USB_BOT_GETLUN_REQUEST 0xFE ///< Get Max Lun | |
#define USB_BOT_CBW_SIGNATURE 0x43425355 ///< dCBWSignature, tag the packet as CBW | |
#define USB_BOT_CSW_SIGNATURE 0x53425355 ///< dCSWSignature, tag the packet as CSW | |
#define USB_BOT_MAX_LUN 0x0F ///< Lun number is from 0 to 15 | |
#define USB_BOT_MAX_CMDLEN 16 ///< Maximum number of command from command set | |
// | |
// Usb BOT command block status values | |
// | |
#define USB_BOT_COMMAND_OK 0x00 ///< Command passed, good status | |
#define USB_BOT_COMMAND_FAILED 0x01 ///< Command failed | |
#define USB_BOT_COMMAND_ERROR 0x02 ///< Phase error, need to reset the device | |
// | |
// Usb Bot retry to get CSW, refers to specification[BOT10-5.3, it says 2 times] | |
// | |
#define USB_BOT_RECV_CSW_RETRY 3 | |
// | |
// Usb Bot wait device reset complete, set by experience | |
// | |
#define USB_BOT_RESET_DEVICE_STALL (100 * USB_MASS_1_MILLISECOND) | |
// | |
// Usb Bot transport timeout, set by experience | |
// | |
#define USB_BOT_SEND_CBW_TIMEOUT (3 * USB_MASS_1_SECOND) | |
#define USB_BOT_RECV_CSW_TIMEOUT (3 * USB_MASS_1_SECOND) | |
#define USB_BOT_RESET_DEVICE_TIMEOUT (3 * USB_MASS_1_SECOND) | |
#pragma pack(1) | |
/// | |
/// The CBW (Command Block Wrapper) structures used by the USB BOT protocol. | |
/// | |
typedef struct { | |
UINT32 Signature; | |
UINT32 Tag; | |
UINT32 DataLen; ///< Length of data between CBW and CSW | |
UINT8 Flag; ///< Bit 7, 0 ~ Data-Out, 1 ~ Data-In | |
UINT8 Lun; ///< Lun number. Bits 0~3 are used | |
UINT8 CmdLen; ///< Length of the command. Bits 0~4 are used | |
UINT8 CmdBlock[USB_BOT_MAX_CMDLEN]; | |
} USB_BOT_CBW; | |
/// | |
/// The and CSW (Command Status Wrapper) structures used by the USB BOT protocol. | |
/// | |
typedef struct { | |
UINT32 Signature; | |
UINT32 Tag; | |
UINT32 DataResidue; | |
UINT8 CmdStatus; | |
} USB_BOT_CSW; | |
#pragma pack() | |
typedef struct { | |
// | |
// Put Interface at the first field to make it easy to distinguish BOT/CBI Protocol instance | |
// | |
EFI_USB_INTERFACE_DESCRIPTOR Interface; | |
EFI_USB_ENDPOINT_DESCRIPTOR *BulkInEndpoint; | |
EFI_USB_ENDPOINT_DESCRIPTOR *BulkOutEndpoint; | |
UINT32 CbwTag; | |
EFI_USB_IO_PROTOCOL *UsbIo; | |
} USB_BOT_PROTOCOL; | |
/** | |
Initializes USB BOT protocol. | |
This function initializes the USB mass storage class BOT protocol. | |
It will save its context which is a USB_BOT_PROTOCOL structure | |
in the Context if Context isn't NULL. | |
@param UsbIo The USB I/O Protocol instance | |
@param Context The buffer to save the context to | |
@retval EFI_SUCCESS The device is successfully initialized. | |
@retval EFI_UNSUPPORTED The transport protocol doesn't support the device. | |
@retval Other The USB BOT initialization fails. | |
**/ | |
EFI_STATUS | |
UsbBotInit ( | |
IN EFI_USB_IO_PROTOCOL *UsbIo, | |
OUT VOID **Context OPTIONAL | |
); | |
/** | |
Call the USB Mass Storage Class BOT protocol to issue | |
the command/data/status circle to execute the commands. | |
@param Context The context of the BOT protocol, that is, | |
USB_BOT_PROTOCOL | |
@param Cmd The high level command | |
@param CmdLen The command length | |
@param DataDir The direction of the data transfer | |
@param Data The buffer to hold data | |
@param DataLen The length of the data | |
@param Lun The number of logic unit | |
@param Timeout The time to wait command | |
@param CmdStatus The result of high level command execution | |
@retval EFI_SUCCESS The command is executed successfully. | |
@retval Other Failed to execute command | |
**/ | |
EFI_STATUS | |
UsbBotExecCommand ( | |
IN VOID *Context, | |
IN VOID *Cmd, | |
IN UINT8 CmdLen, | |
IN EFI_USB_DATA_DIRECTION DataDir, | |
IN VOID *Data, | |
IN UINT32 DataLen, | |
IN UINT8 Lun, | |
IN UINT32 Timeout, | |
OUT UINT32 *CmdStatus | |
); | |
/** | |
Reset the USB mass storage device by BOT protocol. | |
@param Context The context of the BOT protocol, that is, | |
USB_BOT_PROTOCOL. | |
@param ExtendedVerification If FALSE, just issue Bulk-Only Mass Storage Reset request. | |
If TRUE, additionally reset parent hub port. | |
@retval EFI_SUCCESS The device is reset. | |
@retval Others Failed to reset the device.. | |
**/ | |
EFI_STATUS | |
UsbBotResetDevice ( | |
IN VOID *Context, | |
IN BOOLEAN ExtendedVerification | |
); | |
/** | |
Get the max LUN (Logical Unit Number) of USB mass storage device. | |
@param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL | |
@param MaxLun Return pointer to the max number of LUN. (e.g. MaxLun=1 means LUN0 and | |
LUN1 in all.) | |
@retval EFI_SUCCESS Max LUN is got successfully. | |
@retval Others Fail to execute this request. | |
**/ | |
EFI_STATUS | |
UsbBotGetMaxLun ( | |
IN VOID *Context, | |
OUT UINT8 *MaxLun | |
); | |
/** | |
Clean up the resource used by this BOT protocol. | |
@param Context The context of the BOT protocol, that is, USB_BOT_PROTOCOL. | |
@retval EFI_SUCCESS The resource is cleaned up. | |
**/ | |
EFI_STATUS | |
UsbBotCleanUp ( | |
IN VOID *Context | |
); | |
#endif |