X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FUsbIo.h;h=1d102f17aa19350b9bc416f4b0460b766024ac18;hp=ef700d57def9c1197c4486edb43391f9a41897ea;hb=9095d37b8fe5bfc3d02adad6ba7fd7359ebc0107;hpb=3bb398eb6413eedbec1ce7e7452ad043c599b983 diff --git a/MdePkg/Include/Protocol/UsbIo.h b/MdePkg/Include/Protocol/UsbIo.h index ef700d57de..1d102f17aa 100644 --- a/MdePkg/Include/Protocol/UsbIo.h +++ b/MdePkg/Include/Protocol/UsbIo.h @@ -1,12 +1,12 @@ /** @file EFI Usb I/O Protocol as defined in UEFI specification. - This protocol is used by code, typically drivers, running in the EFI - boot services environment to access USB devices like USB keyboards, - mice and mass storage devices. In particular, functions for managing devices + This protocol is used by code, typically drivers, running in the EFI + boot services environment to access USB devices like USB keyboards, + mice and mass storage devices. In particular, functions for managing devices on USB buses are defined here. - - Copyright (c) 2006 - 2008, Intel Corporation - All rights reserved. This program and the accompanying materials + + Copyright (c) 2006 - 2018, 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 @@ -44,9 +44,9 @@ 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 -// +/// +/// USB data transfer direction +/// typedef enum { EfiUsbDataIn, EfiUsbDataOut, @@ -134,13 +134,13 @@ EFI_STATUS 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 The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @@ -148,8 +148,8 @@ EFI_STATUS On input, the size, in bytes, of the data buffer specified by Data. On output, the number of bytes that were actually transferred. @param Timeout Indicating the transfer should be completed within this time frame. - The units are in milliseconds. If Timeout is 0, then the - caller must wait for the function to be completed until + The units are in milliseconds. If Timeout is 0, then the + caller must wait for the function to be completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. @param Status This parameter indicates the USB transfer status. @@ -178,27 +178,27 @@ EFI_STATUS a fixed rate. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @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.This parameter is required when IsNewTransfer is TRUE. The - value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. + executed.This parameter is required when IsNewTransfer is TRUE. The + value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. The units are in milliseconds. @param DataLength Specifies the length, in bytes, of the data to be received from the USB device. This parameter is only required when IsNewTransfer is TRUE. @param InterruptCallback The Callback function. This function is called if the asynchronous - interrupt transfer is completed. This parameter is required + interrupt transfer is completed. This parameter is required when IsNewTransfer is TRUE. - @param Context Data passed to the InterruptCallback function. This is an optional + @param Context Data passed to the InterruptCallback function. This is an optional parameter and may be NULL. @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed. @@ -221,21 +221,21 @@ EFI_STATUS 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 The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @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. If Timeout is 0, - then the caller must wait for the function to be completed - until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the + @param Timeout The time out, in seconds, for this transfer. If Timeout is 0, + then the caller must wait for the function to be completed + until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the transfer is not completed in this time frame, then EFI_TIMEOUT is returned. @param Status This parameter indicates the USB transfer status. @@ -261,13 +261,13 @@ EFI_STATUS transfer is typically used to transfer streaming data. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @@ -296,19 +296,19 @@ EFI_STATUS transfer is typically used to transfer streaming data. @param This A pointer to the EFI_USB_IO_PROTOCOL instance. - @param DeviceEndpoint The destination USB device endpoint to which the - device request is being sent. DeviceEndpoint must - be between 0x01 and 0x0F or between 0x81 and 0x8F, - otherwise EFI_INVALID_PARAMETER is returned. If - the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER - is returned. The MSB of this parameter indicates - the endpoint direction. The number "1" stands for + @param DeviceEndpoint The destination USB device endpoint to which the + device request is being sent. DeviceEndpoint must + be between 0x01 and 0x0F or between 0x81 and 0x8F, + otherwise EFI_INVALID_PARAMETER is returned. If + the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER + is returned. The MSB of this parameter indicates + the endpoint direction. The number "1" stands for an IN endpoint, and "0" stands for an OUT endpoint. @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. This is an optional parameter and may be NULL. - @param IsochronousCallback The IsochronousCallback() function.This function is + @param IsochronousCallback The IsochronousCallback() function.This function is called if the requested isochronous transfer is completed. @param Context Data passed to the IsochronousCallback() function. @@ -426,15 +426,15 @@ EFI_STATUS ); /** - Retrieves a Unicode string stored in a USB Device. + Retrieves a 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.If this function - returns EFI_SUCCESS, it stores the string the caller - wants to get. The caller should release the string + AllocatePool() to store the string.If this function + returns EFI_SUCCESS, it stores the string the caller + wants to get. The caller should release the string buffer with FreePool() after the string is not used any more. @retval EFI_SUCCESS The string was retrieved successfully. @@ -456,9 +456,9 @@ EFI_STATUS @param This A pointer to the EFI_USB_IO_PROTOCOL instance. @param LangIDTable Language ID for the string the caller wants to get. - This is a 16-bit ID defined by Microsoft. This - buffer pointer is allocated and maintained by - the USB Bus Driver, the caller should not modify + This is a 16-bit ID defined by Microsoft. This + buffer pointer is allocated and maintained by + the USB Bus Driver, the caller should not modify its contents. @param TableSize The size, in bytes, of the table LangIDTable. @@ -473,54 +473,13 @@ EFI_STATUS OUT UINT16 *TableSize ); -/** - @par Protocol Description: - The EFI_USB_IO_PROTOCOL provides four basic transfers types described - in the USB 1.1 Specification. These include control transfer, interrupt - transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL - also provides some basic USB device/controller management and configuration - interfaces. A USB device driver uses the services of this protocol to manage USB devices. - - @param UsbControlTransfer - Accesses the USB Device through USB Control Transfer Pipe. - - @param UsbBulkTransfer - Accesses the USB Device through USB Bulk Transfer Pipe. - - @param UsbAsyncInterruptTransfer - Non-block USB interrupt transfer. - - @param UsbSyncInterruptTransfer - Accesses the USB Device through USB Synchronous - Interrupt Transfer Pipe. - - @param UsbIsochronousTransfer - Accesses the USB Device through USB Isochronous Transfer Pipe. - - @param UsbAsyncIsochronousTransfer - Nonblock USB isochronous transfer. - - @param UsbGetDeviceDescriptor - Retrieves the device descriptor of a USB device. - - @param UsbGetConfigDescriptor - Retrieves the activated configuration descriptor of a USB device. - - @param UsbGetInterfaceDescriptor - Retrieves the interface descriptor of a USB Controller. - - @param UsbGetEndpointDescriptor - Retrieves the endpoint descriptor of a USB Controller. - - @param UsbGetStringDescriptor - Retrieves the string descriptor inside a USB Device. - - @param UsbGetSupportedLanguages - Retrieves the array of languages that the USB device supports. - - @param UsbPortReset - Resets and reconfigures the USB controller. -**/ +/// +/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described +/// in the USB 1.1 Specification. These include control transfer, interrupt +/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL +/// also provides some basic USB device/controller management and configuration +/// interfaces. A USB device driver uses the services of this protocol to manage USB devices. +/// struct _EFI_USB_IO_PROTOCOL { // // IO transfer