Retrieve the USB class specific data from the configuration descriptor

If USB device reports class specific descriptors, it is currently the job of
device driver to parse the configuration to find the class specific data.
The new library functions parse the configuration descriptor and return class
specific interface and class specific endpoint descriptors.
Also, these new functions allow to retrieve the data from non-default alternate
settings without performing a switch to this setting. Switching to the
alternate setting currently implies the execution of UsbSetInterface function
that performs USB control trnasfer.
In some cases this switch is not desirable so the new functions
UsbGetInterfaceDescriptorSetting and UsbGetEndpointDescriptorSetting come
in handy.

Signed-off-by: Oleg Ilyasov <olegi@ami.com>

1 files changed, 131 insertions, 0 deletions

diff --git a/MdePkg/Include/Library/UefiUsbLib.h b/MdePkg/Include/Library/UefiUsbLib.h
index a8ab47aeff..fd85be0670 100644
--- a/MdePkg/Include/Library/UefiUsbLib.h
+++ b/MdePkg/Include/Library/UefiUsbLib.h
@@ -3,6 +3,7 @@
   and the standard requests defined in USB 1.1 spec.

 

 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>

+Copyright (c) 2024, American Megatrends Intenational LLC. All rights reserved.<BR>

 SPDX-License-Identifier: BSD-2-Clause-Patent

 

 **/

@@ -552,4 +553,134 @@ UsbClearEndpointHalt (
   OUT UINT32               *Status

   );

 

+/**

+  Retrieve the interface descriptor details from the interface setting.

+

+  This is an extended version of UsbIo->GetInterfaceDescriptor. It returns the interface

+  descriptor for an alternate setting of the interface without executing SET_INTERFACE

+  transfer. It also returns the number of class specific interfaces.

+  AlternateSetting parameter is the zero-based interface descriptor index that is used in USB

+  interface descriptor as USB_INTERFACE_DESCRIPTOR.AlternateSetting.

+

+  @param[in]  This              A pointer to the EFI_USB_IO_PROTOCOL instance.

+  @param[in]  AlternateSetting  Interface alternate setting.

+  @param[out]  Descriptor       The caller allocated buffer to return the contents of the Interface descriptor.

+  @param[out]  CsInterfaceNumber  Number of class specific interfaces for this interface setting.

+

+  @retval EFI_SUCCESS           Output parameters were updated successfully.

+  @retval EFI_INVALID_PARAMETER Descriptor or CsInterfaceNumber is NULL.

+  @retval EFI_UNSUPPORTED       Setting is greater than the number of alternate settings in this interface.

+  @retval EFI_DEVICE_ERROR      Error reading device data.

+

+**/

+EFI_STATUS

+EFIAPI

+UsbGetInterfaceDescriptorSetting (

+  IN  EFI_USB_IO_PROTOCOL           *This,

+  IN  UINT16                        AlternateSetting,

+  OUT EFI_USB_INTERFACE_DESCRIPTOR  *Descriptor,

+  OUT UINTN                         *CsInterfacesNumber

+  );

+

+/**

+  Retrieve the endpoint descriptor from the interface setting.

+

+  This is an extended version of UsbIo->GetEndpointDescriptor. It returns the endpoint

+  descriptor for an alternate setting of a given interface.

+  AlternateSetting parameter is the zero-based interface descriptor index that is used in USB

+  interface descriptor as USB_INTERFACE_DESCRIPTOR.AlternateSetting.

+

+  Note: The total number of endpoints can be retrieved from the interface descriptor

+  returned by EDKII_USBIO_EXT_GET_INTERFACE_DESCRIPTOR function.

+

+  @param[in]  This              A pointer to the EFI_USB_IO_PROTOCOL instance.

+  @param[in]  AlternateSetting  Interface alternate setting.

+  @param[in]  Index             Index of the endpoint to retrieve. The valid range is 0..15.

+  @param[out]  Descriptor       A pointer to the caller allocated USB Interface Descriptor.

+

+  @retval EFI_SUCCESS           Output parameters were updated successfully.

+  @retval EFI_INVALID_PARAMETER Descriptor is NULL.

+  @retval EFI_UNSUPPORTED       Setting is greater than the number of alternate settings in this interface.

+  @retval EFI_NOT_FOUND         Index is greater than the number of endpoints in this interface.

+  @retval EFI_DEVICE_ERROR      Error reading device data.

+

+**/

+EFI_STATUS

+EFIAPI

+UsbGetEndpointDescriptorSetting (

+  IN  EFI_USB_IO_PROTOCOL          *This,

+  IN  UINT16                       AlternateSetting,

+  IN  UINTN                        Index,

+  OUT EFI_USB_ENDPOINT_DESCRIPTOR  *Descriptor

+  );

+

+/**

+  Retrieve class specific interface descriptor.

+

+  AlternateSetting parameter is the zero-based interface descriptor index that is used in USB

+  interface descriptor as USB_INTERFACE_DESCRIPTOR.AlternateSetting.

+

+  @param[in]  This              A pointer to the EFI_USB_IO_PROTOCOL instance.

+  @param[in]  AlternateSetting  Interface alternate setting.

+  @param[in]  Index             Zero-based index of the class specific interface.

+  @param[in][out]  BufferSize   On input, the size in bytes of the return Descriptor buffer.

+                                On output the size of data returned in Descriptor.

+  @param[out]  Descriptor       The buffer to return the contents of the class specific interface descriptor. May

+                                be NULL with a zero BufferSize in order to determine the size buffer needed.

+

+  @retval EFI_SUCCESS           Output parameters were updated successfully.

+  @retval EFI_INVALID_PARAMETER BufferSize is NULL.

+                                Buffer is NULL and *BufferSize is not zero.

+  @retval EFI_UNSUPPORTED       Setting is greater than the number of alternate settings in this interface.

+  @retval EFI_NOT_FOUND         Index is greater than the number of class specific interfaces.

+  @retval EFI_BUFFER_TOO_SMALL  The BufferSize is too small for the result. BufferSize has been updated with the size

+                                needed to complete the request.

+  @retval EFI_DEVICE_ERROR      Error reading device data.

+

+**/

+EFI_STATUS

+EFIAPI

+UsbGetCsInterfaceDescriptor (

+  IN  EFI_USB_IO_PROTOCOL  *This,

+  IN  UINT16               AlternateSetting,

+  IN  UINTN                Index,

+  IN OUT UINTN             *BufferSize,

+  OUT VOID                 *Buffer

+  );

+

+/**

+  Retrieve class specific endpoint descriptor.

+

+  AlternateSetting parameter is the zero-based interface descriptor index that is used in USB

+  interface descriptor as USB_INTERFACE_DESCRIPTOR.AlternateSetting.

+

+  @param[in]  This              A pointer to the EFI_USB_IO_PROTOCOL instance.

+  @param[in]  AlternateSetting  Interface alternate setting.

+  @param[in]  Index             Zero-based index of the non-zero endpoint.

+  @param[in][out]  BufferSize   On input, the size in bytes of the return Descriptor buffer.

+                                On output the size of data returned in Descriptor.

+  @param[out]  Descriptor       The buffer to return the contents of the class specific endpoint descriptor. May

+                                be NULL with a zero BufferSize in order to determine the size buffer needed.

+

+  @retval EFI_SUCCESS           Output parameters were updated successfully.

+  @retval EFI_INVALID_PARAMETER BufferSize is NULL.

+                                Buffer is NULL and *BufferSize is not zero.

+  @retval EFI_UNSUPPORTED       Setting is greater than the number of alternate settings in this interface.

+  @retval EFI_NOT_FOUND         Index is greater than the number of endpoints in this interface.

+                                Endpoint does not have class specific endpoint descriptor.

+  @retval EFI_BUFFER_TOO_SMALL  The BufferSize is too small for the result. BufferSize has been updated with the size

+                                needed to complete the request.

+  @retval EFI_DEVICE_ERROR      Error reading device data.

+

+**/

+EFI_STATUS

+EFIAPI

+UsbGetCsEndpointDescriptor (

+  IN  EFI_USB_IO_PROTOCOL  *This,

+  IN  UINT16               AlternateSetting,

+  IN  UINTN                Index,

+  IN OUT UINTN             *BufferSize,

+  OUT VOID                 *Buffer

+  );

+

 #endif