X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FUsbIo.h;h=7d6ce276ab434b10c158652254e8ec3234ef7102;hp=47de143d852e900b2117e0b3229a7c809b094e33;hb=e3c6b3d9802d267eff1c45c843a112c4c800334e;hpb=511710d68f477e0210ae1830769e5d0cde4ea36a diff --git a/MdePkg/Include/Protocol/UsbIo.h b/MdePkg/Include/Protocol/UsbIo.h index 47de143d85..7d6ce276ab 100644 --- a/MdePkg/Include/Protocol/UsbIo.h +++ b/MdePkg/Include/Protocol/UsbIo.h @@ -1,22 +1,22 @@ /** @file EFI Usb I/O Protocol - Copyright (c) 2006, 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 - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2006, 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 + http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - Module Name: UsbIo.h + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ #ifndef __USB_IO_H__ #define __USB_IO_H__ +#include + // // Global ID for the USB I/O Protocol // @@ -27,19 +27,55 @@ typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL; -/** +// +// Related Definition for EFI USB I/O protocol +// + +// +// USB standard descriptors and reqeust +// +typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST; +typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR; +typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR; +typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR; +typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR; + +// +// USB data transfer direction +// +typedef enum { + EfiUsbDataIn, + EfiUsbDataOut, + EfiUsbNoData +} EFI_USB_DATA_DIRECTION; + +// +// USB Transfer Results +// +#define EFI_USB_NOERROR 0x00 +#define EFI_USB_ERR_NOTEXECUTE 0x01 +#define EFI_USB_ERR_STALL 0x02 +#define EFI_USB_ERR_BUFFER 0x04 +#define EFI_USB_ERR_BABBLE 0x08 +#define EFI_USB_ERR_NAK 0x10 +#define EFI_USB_ERR_CRC 0x20 +#define EFI_USB_ERR_TIMEOUT 0x40 +#define EFI_USB_ERR_BITSTUFF 0x80 +#define EFI_USB_ERR_SYSTEM 0x100 + +/** Async USB transfer callback routine. - + @param Data Data received or sent via the USB Asynchronous Transfer, if the - transfer completed successfully. + transfer completed successfully. @param DataLength The length of Data received or sent via the Asynchronous - Transfer, if transfer successfully completes. + Transfer, if transfer successfully completes. @param Context Data passed from UsbAsyncInterruptTransfer() request. @param Status Indicates the result of the asynchronous transfer. - - @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed. + + @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed. @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. - + **/ typedef EFI_STATUS @@ -55,27 +91,27 @@ EFI_STATUS // -/** +/** This function is used to manage a USB device with a control transfer pipe. A control transfer is - typically used to perform device initialization and configuration. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + typically used to perform device initialization and configuration. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param Request A pointer to the USB device request that will be sent to the USB - device. + device. @param Direction Indicates the data direction. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. + device or received from USB device. @param Timeout Indicating the transfer should be completed within this time frame. - The units are in milliseconds. + The units are in milliseconds. @param DataLength The size, in bytes, of the data buffer specified by Data. @param Status A pointer to the result of the USB transfer. - + @retval EFI_SUCCESS The control transfer has been successfully executed. @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status. @retval EFI_INVALID_PARAMETE One or more parameters are invalid. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. @retval EFI_TIMEOUT The control transfer fails due to timeout. - + **/ typedef EFI_STATUS @@ -89,26 +125,26 @@ EFI_STATUS OUT UINT32 *Status ); -/** +/** This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are typically used to transfer large amounts of data to/from USB devices. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB - device. + device. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. + device or received from USB device. @param DataLength The size, in bytes, of the data buffer specified by Data. @param Timeout Indicating the transfer should be completed within this time frame. - The units are in milliseconds. + The units are in milliseconds. @param Status This parameter indicates the USB transfer status. - + @retval EFI_SUCCESS The bulk transfer has been successfully executed. @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status. @retval EFI_INVALID_PARAMETE One or more parameters are invalid. @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. @retval EFI_TIMEOUT The control transfer fails due to timeout. - + **/ typedef EFI_STATUS @@ -121,29 +157,29 @@ EFI_STATUS OUT UINT32 *Status ); -/** - This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous - Interrupt Transfer is typically used to query a device's status at a fixed rate. For example, +/** + This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous + Interrupt Transfer is typically used to query a device's status at a fixed rate. For example, keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at - a fixed rate. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + a fixed rate. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB - device. - @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If + device. + @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If FALSE, the interrupt transfer is deleted from the device's interrupt - transfer queue. - @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be - executed. + transfer queue. + @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be + executed. @param DataLength Specifies the length, in bytes, of the data to be received from the - USB device. + USB device. @param Context Data passed to the InterruptCallback function. @param InterruptCallback The Callback function. This function is called if the asynchronous interrupt transfer is completed. - + @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed. - @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. - + @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. + **/ typedef EFI_STATUS @@ -157,24 +193,24 @@ EFI_STATUS IN VOID *Context OPTIONAL ); -/** +/** This function is used to manage a USB device with an interrupt transfer pipe. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB - device. + device. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. + device or received from USB device. @param DataLength On input, then size, in bytes, of the buffer Data. On output, the - amount of data actually transferred. + amount of data actually transferred. @param Timeout The time out, in seconds, for this transfer. - @param Status This parameter indicates the USB transfer status. - + @param Status This parameter indicates the USB transfer status. + @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. - @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed. + @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed. @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. - @retval EFI_TIMEOUT The transfer fails due to timeout. + @retval EFI_TIMEOUT The transfer fails due to timeout. **/ typedef EFI_STATUS @@ -187,24 +223,24 @@ EFI_STATUS OUT UINT32 *Status ); -/** +/** This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous transfer is typically used to transfer streaming data. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB - device. + device. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. - @param DataLength The size, in bytes, of the data buffer specified by Data. - @param Status This parameter indicates the USB transfer status. - + device or received from USB device. + @param DataLength The size, in bytes, of the data buffer specified by Data. + @param Status This parameter indicates the USB transfer status. + @retval EFI_SUCCESS The isochronous transfer has been successfully executed. @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid. @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status - is returned in Status. + is returned in Status. @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. - @retval EFI_TIMEOUT The transfer fails due to timeout. + @retval EFI_TIMEOUT The transfer fails due to timeout. **/ typedef EFI_STATUS @@ -216,24 +252,24 @@ EFI_STATUS OUT UINT32 *Status ); -/** +/** This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous - transfer is typically used to transfer streaming data. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + transfer is typically used to transfer streaming data. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB - device. + device. @param Data A pointer to the buffer of data that will be transmitted to USB - device or received from USB device. - @param DataLength The size, in bytes, of the data buffer specified by Data. + device or received from USB device. + @param DataLength The size, in bytes, of the data buffer specified by Data. @param Context Data passed to the IsochronousCallback() function. @param IsochronousCallback The IsochronousCallback() function. - + @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted to the system. @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid. @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. - + **/ typedef EFI_STATUS @@ -246,16 +282,16 @@ EFI_STATUS IN VOID *Context OPTIONAL ); -/** +/** Resets and reconfigures the USB controller. This function will work for all USB devices except - USB Hub Controllers. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - - @retval EFI_SUCCESS The USB controller was reset. + USB Hub Controllers. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @retval EFI_SUCCESS The USB controller was reset. @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub. @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process. - + **/ typedef EFI_STATUS @@ -263,16 +299,16 @@ EFI_STATUS IN EFI_USB_IO_PROTOCOL *This ); -/** +/** Retrieves the USB Device Descriptor. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor. - + @retval EFI_SUCCESS The device descriptor was retrieved successfully. @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL. @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured. - + **/ typedef EFI_STATUS @@ -281,17 +317,17 @@ EFI_STATUS OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor ); -/** +/** Retrieves the USB Device Descriptor. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration - Descriptor. + Descriptor. @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully. @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL. @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not - be configured. - + be configured. + **/ typedef EFI_STATUS @@ -300,18 +336,18 @@ EFI_STATUS OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor ); -/** +/** Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface - within a USB device is equivalently to a USB Controller within the current configuration. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + within a USB device is equivalently to a USB Controller within the current configuration. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within - the configuration setting. + the configuration setting. @retval EFI_SUCCESS The interface descriptor retrieved successfully. @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL. @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be - correctly configured. - + correctly configured. + **/ typedef EFI_STATUS @@ -320,19 +356,19 @@ EFI_STATUS OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor ); -/** +/** Retrieves an Endpoint Descriptor within a USB Controller. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param EndpointIndex Indicates which endpoint descriptor to retrieve. @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of - a USB controller. - + a USB controller. + @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully. @retval EFI_INVALID_PARAMETER One or more parameters are invalid. @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be - correctly configured. - + correctly configured. + **/ typedef EFI_STATUS @@ -342,19 +378,19 @@ EFI_STATUS OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor ); -/** +/** Retrieves a Unicode string stored in a USB Device. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param LangID The Language ID for the string being retrieved. - @param StringID The ID of the string being retrieved. - @param String A pointer to a buffer allocated by this function with + @param StringID The ID of the string being retrieved. + @param String A pointer to a buffer allocated by this function with AllocatePool() to store the string. - - @retval EFI_SUCCESS The string was retrieved successfully. - @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found. + + @retval EFI_SUCCESS The string was retrieved successfully. + @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found. @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String. - + **/ typedef EFI_STATUS @@ -365,15 +401,15 @@ EFI_STATUS OUT CHAR16 **String ); -/** +/** Retrieves all the language ID codes that the USB device supports. - - @param This A pointer to the EFI_USB_IO_PROTOCOL instance. + + @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param LangIDTable Language ID for the string the caller wants to get. @param TableSize The size, in bytes, of the table LangIDTable. - - @retval EFI_SUCCESS The support languages were retrieved successfully. - + + @retval EFI_SUCCESS The support languages were retrieved successfully. + **/ typedef EFI_STATUS