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 <[email protected]>
NVIDIA · Dec 13, 2024 · 1a440d9 · 1a440d9
1 parent c7354e9
commit 1a440d9
Show file tree

Hide file tree

Showing 4 changed files with 669 additions and 0 deletions.
diff --git 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
diff --git a/MdePkg/Library/UefiUsbLib/UefiUsbLib.inf b/MdePkg/Library/UefiUsbLib/UefiUsbLib.inf
@@ -5,6 +5,7 @@
 # Usb Hid 1.1 spec and the standard requests defined in Usb 1.1 spec.
 #
 # Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
+# Copyright (c) 2024, American Megatrends International LLC. All rights reserved.<BR>
 #
 #  SPDX-License-Identifier: BSD-2-Clause-Patent
 #
@@ -19,6 +20,7 @@
   MODULE_TYPE                    = UEFI_DRIVER
   VERSION_STRING                 = 1.0
   LIBRARY_CLASS                  = UefiUsbLib|DXE_DRIVER DXE_RUNTIME_DRIVER DXE_SMM_DRIVER UEFI_APPLICATION UEFI_DRIVER
+  DESTRUCTOR                     = UefiUsbLibDestructor
 
 
 #
@@ -37,6 +39,7 @@
   DebugLib
   BaseMemoryLib
   PcdLib
+  UefiBootServicesTableLib
 
 [Pcd]
   gEfiMdePkgTokenSpaceGuid.PcdUsbTransferTimeoutValue  ## CONSUMES

diff --git a/MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h b/MdePkg/Library/UefiUsbLib/UefiUsbLibInternal.h
@@ -5,6 +5,7 @@
   This file includes package header files, library classes and protocol, PPI & GUID definitions.
 
   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2024, American Megatrends International LLC. All rights reserved.<BR>
    SPDX-License-Identifier: BSD-2-Clause-Patent
 **/
 
@@ -17,6 +18,7 @@
 #include <Library/BaseMemoryLib.h>
 #include <Library/DebugLib.h>
 #include <Library/PcdLib.h>
+#include <Library/UefiBootServicesTableLib.h>
 
 #include <IndustryStandard/Usb.h>