text: /**
   * @file UsbDescriptors.h
   * @brief Functions to read USB Interface and Capabilities descriptors
   *
   * Copyright (c) 2018-2019, DisplayLink (UK) Ltd. All rights reserved.
   *
   * SPDX-License-Identifier: BSD-2-Clause-Patent
   *
  **/
  
  #ifndef USB_DESCRIPTORS_H_
  #define USB_DESCRIPTORS_H_
  
    /**
    Type of the Direct Framebuffer capability descriptor.
    This is a vendor specific USB descriptor for DisplayLink.
    @see NR-140082 Section 3.5
    **/
  #define DESCRIPTOR_TYPE_DIRECTFB_CAPABILITY 0x5e
  
    /**
    Identifiers for capabllity keys
    @see NR-140082 Section 3.2
    **/
  
    /**
    Key for Capabilities 1 - See section 3.2.1
    **/
  #define CAPABILITIES1_KEY 0x0
  
    /**
    Lengths for capabllity fields
    **/
  #define CAPABILITIES1_LENGTH 0x4
  
    /**
    Bits for the capability bitmask Capabilities1
    **/
  
    /**
    This is the first capability defined for the protocol.
    It represents the mode of operation as of initial release.
    If a device ever breaks compatibility with this initial release,
    it will cease
    to support CapabilityBaseProtocol.
    **/
  #define CAPABILITIES1_BASE_PROTOCOL (1 << 0)
  
    /**
    Idealised VendorDescriptor which is the result
    of parsing vendor descriptor from device.
    **/
    typedef struct {
      UINT32 Capabilities1;
    } VendorDescriptor;
  
  #pragma pack(push, 1)
    typedef struct {
      UINT16 Key; /** Really of type enum DescrptorKeys */
      UINT8 Length;
      UINT8 Value[];
    } DescriptorKLV;
  
    typedef struct {
      UINT8 Length;
      UINT8 Type;
      UINT16 CapabilityVersion;
      UINT8 CapabilityLength;
      UINT8 Klv[];
    } VendorDescriptorGeneric;
  #pragma pack(pop)
  
  
  EFI_STATUS UsbDisplayLinkGetInterfaceDescriptor (
      IN EFI_USB_IO_PROTOCOL *UsbIo,
      EFI_USB_INTERFACE_DESCRIPTOR* InterfaceDescriptor,
      UINT8 index
      );
  
  EFI_STATUS ReadCapabilitiesDescriptor (IN EFI_USB_IO_PROTOCOL *UsbIo, VOID* Buffer, UINT16 Length);
  
  /**
  Parse data in buffer to a VendorDescriptor, if possible.
  
  @param Data      Buffer
  @param Length    Length of buffer
  
  @retval EFI_SUCCESS      The descriptor was parsed successfully
  @retval EFI_UNSUPPORTED  Simple Pointer Protocol is not installed on Controller.
  **/
  EFI_STATUS
  UsbDisplayLinkParseCapabilitiesDescriptor (
    CONST IN VOID* Data,
    IN UINTN Length,
    OUT VendorDescriptor* Descriptor
  );
  
  /**
  Decide if binding may proceed, given capabilities
  
  @retval TRUE   Binding may proceed
  @retval FALSE  Binding is not possible
  **/
  BOOLEAN
  UsbDisplayLinkCapabilitiesSufficientToBind (
    CONST IN VendorDescriptor* Descriptor
  );
  
  #endif // USB_DESCRIPTORS_H_
  