/** @file\r
EFI Usb I/O Protocol as defined in UEFI specification.\r
- This protocol is used by code, typically drivers, running in the EFI \r
- boot services environment to access USB devices like USB keyboards, \r
- mice and mass storage devices. In particular, functions for managing devices \r
+ This protocol is used by code, typically drivers, running in the EFI\r
+ boot services environment to access USB devices like USB keyboards,\r
+ mice and mass storage devices. In particular, functions for managing devices\r
on USB buses are defined here.\r
- \r
- Copyright (c) 2006 - 2008, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
- are licensed and made available under the terms and conditions of the BSD License\r
- which accompanies this distribution. The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR;\r
typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR;\r
\r
-//\r
-// USB data transfer direction\r
-//\r
+///\r
+/// USB data transfer direction\r
+///\r
typedef enum {\r
EfiUsbDataIn,\r
EfiUsbDataOut,\r
typically used to transfer large amounts of data to/from USB devices.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
- @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
- device.\r
+ @param DeviceEndpoint The destination USB device endpoint to which the\r
+ device request is being sent. DeviceEndpoint must\r
+ be between 0x01 and 0x0F or between 0x81 and 0x8F,\r
+ otherwise EFI_INVALID_PARAMETER is returned. If\r
+ the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER\r
+ is returned. The MSB of this parameter indicates\r
+ the endpoint direction. The number "1" stands for\r
+ an IN endpoint, and "0" stands for an OUT endpoint.\r
@param Data A pointer to the buffer of data that will be transmitted to USB\r
device or received from USB device.\r
@param DataLength The size, in bytes, of the data buffer specified by Data.\r
+ On input, the size, in bytes, of the data buffer specified by Data.\r
+ On output, the number of bytes that were actually transferred.\r
@param Timeout Indicating the transfer should be completed within this time frame.\r
- The units are in milliseconds.\r
+ The units are in milliseconds. If Timeout is 0, then the\r
+ caller must wait for the function to be completed until\r
+ EFI_SUCCESS or EFI_DEVICE_ERROR is returned.\r
@param Status This parameter indicates the USB transfer status.\r
\r
@retval EFI_SUCCESS The bulk transfer has been successfully executed.\r
a fixed rate.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
- @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
- device.\r
+ @param DeviceEndpoint The destination USB device endpoint to which the\r
+ device request is being sent. DeviceEndpoint must\r
+ be between 0x01 and 0x0F or between 0x81 and 0x8F,\r
+ otherwise EFI_INVALID_PARAMETER is returned. If\r
+ the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER\r
+ is returned. The MSB of this parameter indicates\r
+ the endpoint direction. The number "1" stands for\r
+ an IN endpoint, and "0" stands for an OUT endpoint.\r
@param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If\r
FALSE, the interrupt transfer is deleted from the device's interrupt\r
transfer queue.\r
@param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be\r
- executed.\r
+ executed.This parameter is required when IsNewTransfer is TRUE. The\r
+ value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned.\r
+ The units are in milliseconds.\r
@param DataLength Specifies the length, in bytes, of the data to be received from the\r
- USB device.\r
+ USB device. This parameter is only required when IsNewTransfer is TRUE.\r
@param InterruptCallback The Callback function. This function is called if the asynchronous\r
- interrupt transfer is completed.\r
- @param Context Data passed to the InterruptCallback function.\r
+ interrupt transfer is completed. This parameter is required\r
+ when IsNewTransfer is TRUE.\r
+ @param Context Data passed to the InterruptCallback function. This is an optional\r
+ parameter and may be NULL.\r
\r
@retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.\r
@retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.\r
This function is used to manage a USB device with an interrupt transfer pipe.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
- @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
- device.\r
+ @param DeviceEndpoint The destination USB device endpoint to which the\r
+ device request is being sent. DeviceEndpoint must\r
+ be between 0x01 and 0x0F or between 0x81 and 0x8F,\r
+ otherwise EFI_INVALID_PARAMETER is returned. If\r
+ the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER\r
+ is returned. The MSB of this parameter indicates\r
+ the endpoint direction. The number "1" stands for\r
+ an IN endpoint, and "0" stands for an OUT endpoint.\r
@param Data A pointer to the buffer of data that will be transmitted to USB\r
device or received from USB device.\r
@param DataLength On input, then size, in bytes, of the buffer Data. On output, the\r
amount of data actually transferred.\r
- @param Timeout The time out, in seconds, for this transfer.\r
+ @param Timeout The time out, in seconds, for this transfer. If Timeout is 0,\r
+ then the caller must wait for the function to be completed\r
+ until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the\r
+ transfer is not completed in this time frame, then EFI_TIMEOUT is returned.\r
@param Status This parameter indicates the USB transfer status.\r
\r
@retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.\r
transfer is typically used to transfer streaming data.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
- @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
- device.\r
+ @param DeviceEndpoint The destination USB device endpoint to which the\r
+ device request is being sent. DeviceEndpoint must\r
+ be between 0x01 and 0x0F or between 0x81 and 0x8F,\r
+ otherwise EFI_INVALID_PARAMETER is returned. If\r
+ the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER\r
+ is returned. The MSB of this parameter indicates\r
+ the endpoint direction. The number "1" stands for\r
+ an IN endpoint, and "0" stands for an OUT endpoint.\r
@param Data A pointer to the buffer of data that will be transmitted to USB\r
device or received from USB device.\r
@param DataLength The size, in bytes, of the data buffer specified by Data.\r
transfer is typically used to transfer streaming data.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
- @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
- device.\r
+ @param DeviceEndpoint The destination USB device endpoint to which the\r
+ device request is being sent. DeviceEndpoint must\r
+ be between 0x01 and 0x0F or between 0x81 and 0x8F,\r
+ otherwise EFI_INVALID_PARAMETER is returned. If\r
+ the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER\r
+ is returned. The MSB of this parameter indicates\r
+ the endpoint direction. The number "1" stands for\r
+ an IN endpoint, and "0" stands for an OUT endpoint.\r
@param Data A pointer to the buffer of data that will be transmitted to USB\r
device or received from USB device.\r
@param DataLength The size, in bytes, of the data buffer specified by Data.\r
- @param IsochronousCallback The IsochronousCallback() function.\r
+ This is an optional parameter and may be NULL.\r
+ @param IsochronousCallback The IsochronousCallback() function.This function is\r
+ called if the requested isochronous transfer is completed.\r
@param Context Data passed to the IsochronousCallback() function.\r
\r
@retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted\r
);\r
\r
/**\r
- Retrieves a Unicode string stored in a USB Device.\r
+ Retrieves a string stored in a USB Device.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
@param LangID The Language ID for the string being retrieved.\r
@param StringID The ID of the string being retrieved.\r
@param String A pointer to a buffer allocated by this function with\r
- AllocatePool() to store the string.\r
+ AllocatePool() to store the string.If this function\r
+ returns EFI_SUCCESS, it stores the string the caller\r
+ wants to get. The caller should release the string\r
+ buffer with FreePool() after the string is not used any more.\r
\r
@retval EFI_SUCCESS The string was retrieved successfully.\r
@retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.\r
\r
@param This A pointer to the EFI_USB_IO_PROTOCOL instance.\r
@param LangIDTable Language ID for the string the caller wants to get.\r
+ This is a 16-bit ID defined by Microsoft. This\r
+ buffer pointer is allocated and maintained by\r
+ the USB Bus Driver, the caller should not modify\r
+ its contents.\r
@param TableSize The size, in bytes, of the table LangIDTable.\r
\r
@retval EFI_SUCCESS The support languages were retrieved successfully.\r
OUT UINT16 *TableSize\r
);\r
\r
-/** \r
- @par Protocol Description:\r
- The EFI_USB_IO_PROTOCOL provides four basic transfers types described \r
- in the USB 1.1 Specification. These include control transfer, interrupt \r
- transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL \r
- also provides some basic USB device/controller management and configuration \r
- interfaces. A USB device driver uses the services of this protocol to manage USB devices. \r
-\r
- @param UsbControlTransfer \r
- Accesses the USB Device through USB Control Transfer Pipe. \r
-\r
- @param UsbBulkTransfer\r
- Accesses the USB Device through USB Bulk Transfer Pipe. \r
-\r
- @param UsbAsyncInterruptTransfer\r
- Non-block USB interrupt transfer. \r
-\r
- @param UsbSyncInterruptTransfer\r
- Accesses the USB Device through USB Synchronous\r
- Interrupt Transfer Pipe. \r
-\r
- @param UsbIsochronousTransfer\r
- Accesses the USB Device through USB Isochronous Transfer Pipe. \r
-\r
- @param UsbAsyncIsochronousTransfer\r
- Nonblock USB isochronous transfer. \r
-\r
- @param UsbGetDeviceDescriptor\r
- Retrieves the device descriptor of a USB device. \r
-\r
- @param UsbGetConfigDescriptor\r
- Retrieves the activated configuration descriptor of a USB device. \r
-\r
- @param UsbGetInterfaceDescriptor\r
- Retrieves the interface descriptor of a USB Controller. \r
-\r
- @param UsbGetEndpointDescriptor\r
- Retrieves the endpoint descriptor of a USB Controller. \r
-\r
- @param UsbGetStringDescriptor\r
- Retrieves the string descriptor inside a USB Device. \r
-\r
- @param UsbGetSupportedLanguages\r
- Retrieves the array of languages that the USB device supports. \r
-\r
- @param UsbPortReset\r
- Resets and reconfigures the USB controller. \r
-**/\r
+///\r
+/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described\r
+/// in the USB 1.1 Specification. These include control transfer, interrupt\r
+/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL\r
+/// also provides some basic USB device/controller management and configuration\r
+/// interfaces. A USB device driver uses the services of this protocol to manage USB devices.\r
+///\r
struct _EFI_USB_IO_PROTOCOL {\r
//\r
// IO transfer\r