diff options
Diffstat (limited to 'MdePkg/Include/Protocol/UsbIo.h')
| -rw-r--r-- | MdePkg/Include/Protocol/UsbIo.h | 418 |
1 files changed, 418 insertions, 0 deletions
diff --git a/MdePkg/Include/Protocol/UsbIo.h b/MdePkg/Include/Protocol/UsbIo.h new file mode 100644 index 0000000000..30309e3035 --- /dev/null +++ b/MdePkg/Include/Protocol/UsbIo.h @@ -0,0 +1,418 @@ +/** @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
+
+ 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
+
+**/
+
+#ifndef __USB_IO_H__
+#define __USB_IO_H__
+
+//
+// Global ID for the USB I/O Protocol
+//
+#define EFI_USB_IO_PROTOCOL_GUID \
+ { \
+ 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
+ }
+
+typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;
+
+/**
+ Async USB transfer callback routine.
+
+ @param Data Data received or sent via the USB Asynchronous Transfer, if the
+ transfer completed successfully.
+ @param DataLength The length of Data received or sent via the Asynchronous
+ 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_DEVICE_ERROR The asynchronous USB transfer request failed.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK) (
+ IN VOID *Data,
+ IN UINTN DataLength,
+ IN VOID *Context,
+ IN UINT32 Status
+ );
+
+//
+// Prototype for EFI USB I/O protocol
+//
+
+
+/**
+ 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.
+ @param Request A pointer to the USB device request that will be sent to the USB
+ 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.
+ @param Timeout Indicating the transfer should be completed within this time frame.
+ 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
+(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN EFI_USB_DEVICE_REQUEST *Request,
+ IN EFI_USB_DATA_DIRECTION Direction,
+ IN UINT32 Timeout,
+ IN OUT VOID *Data OPTIONAL,
+ IN UINTN DataLength OPTIONAL,
+ 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 DeviceEndpoint A pointer to the USB device request that will be sent to the USB
+ 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 Timeout Indicating the transfer should be completed within this time frame.
+ 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
+(EFIAPI *EFI_USB_IO_BULK_TRANSFER) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT8 DeviceEndpoint,
+ IN OUT VOID *Data,
+ IN OUT UINTN *DataLength,
+ IN UINTN Timeout,
+ 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,
+ 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.
+ @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
+ 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.
+ @param DataLength Specifies the length, in bytes, of the data to be received from the
+ 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.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT8 DeviceEndpoint,
+ IN BOOLEAN IsNewTransfer,
+ IN UINTN PollingInterval OPTIONAL,
+ IN UINTN DataLength OPTIONAL,
+ IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,
+ 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 DeviceEndpoint A pointer to the USB device request that will be sent to the USB
+ device.
+ @param Data A pointer to the buffer of data that will be transmitted to USB
+ 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.
+ @param Timeout The time out, in seconds, for this transfer.
+ @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_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
+ @retval EFI_TIMEOUT The transfer fails due to timeout.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT8 DeviceEndpoint,
+ IN OUT VOID *Data,
+ IN OUT UINTN *DataLength,
+ IN UINTN Timeout,
+ 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 DeviceEndpoint A pointer to the USB device request that will be sent to the USB
+ 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.
+
+ @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.
+ @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.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT8 DeviceEndpoint,
+ IN OUT VOID *Data,
+ IN UINTN DataLength,
+ 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 DeviceEndpoint A pointer to the USB device request that will be sent to the USB
+ 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 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
+(EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT8 DeviceEndpoint,
+ IN OUT VOID *Data,
+ IN UINTN DataLength,
+ IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,
+ 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.
+ @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
+(EFIAPI *EFI_USB_IO_PORT_RESET) (
+ IN EFI_USB_IO_PROTOCOL *This
+ );
+
+/**
+ Retrieves the USB Device Descriptor.
+
+ @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
+(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor
+ );
+
+/**
+ Retrieves the USB Device Descriptor.
+
+ @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
+ @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
+ 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.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ 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.
+ @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
+ 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.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ 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 EndpointIndex Indicates which endpoint descriptor to retrieve.
+ @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
+ 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.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT8 EndpointIndex,
+ 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 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
+ 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_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ IN UINT16 LangID,
+ IN UINT8 StringID,
+ 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 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.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE) (
+ IN EFI_USB_IO_PROTOCOL *This,
+ OUT UINT16 **LangIDTable,
+ OUT UINT16 *TableSize
+ );
+
+//
+// Protocol Interface Structure
+//
+struct _EFI_USB_IO_PROTOCOL {
+ //
+ // IO transfer
+ //
+ EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer;
+ EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer;
+ EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer;
+ EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer;
+ EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer;
+ EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;
+
+ //
+ // Common device request
+ //
+ EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor;
+ EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor;
+ EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor;
+ EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor;
+ EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor;
+ EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages;
+
+ //
+ // Reset controller's parent port
+ //
+ EFI_USB_IO_PORT_RESET UsbPortReset;
+};
+
+extern EFI_GUID gEfiUsbIoProtocolGuid;
+
+#endif
|