MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbBusDxe / UsbDesc.h

/** @file\r
\r
    Manage Usb Descriptor List\r
\r
Copyright (c) 2007 - 2014, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _USB_DESCRIPTOR_H_\r
#define _USB_DESCRIPTOR_H_\r
\r
#define USB_MAX_INTERFACE_SETTING  256\r
\r
//\r
// The RequestType in EFI_USB_DEVICE_REQUEST is composed of\r
// three fields: One bit direction, 2 bit type, and 5 bit\r
// target.\r
//\r
#define USB_REQUEST_TYPE(Dir, Type, Target) \\r
          ((UINT8)((((Dir) == EfiUsbDataIn ? 0x01 : 0) << 7) | (Type) | (Target)))\r
\r
//\r
// A common header for usb standard descriptor.\r
// Each stand descriptor has a length and type.\r
//\r
#pragma pack(1)\r
typedef struct {\r
  UINT8                   Len;\r
  UINT8                   Type;\r
} USB_DESC_HEAD;\r
#pragma pack()\r
\r
\r
//\r
// Each USB device has a device descriptor. Each device may\r
// have several configures. Each configure contains several\r
// interfaces. Each interface may have several settings. Each\r
// setting has several endpoints.\r
//\r
// EFI_USB_..._DESCRIPTOR must be the first member of the\r
// structure.\r
//\r
typedef struct {\r
  EFI_USB_ENDPOINT_DESCRIPTOR   Desc;\r
  UINT8                         Toggle;\r
} USB_ENDPOINT_DESC;\r
\r
typedef struct {\r
  EFI_USB_INTERFACE_DESCRIPTOR  Desc;\r
  USB_ENDPOINT_DESC             **Endpoints;\r
} USB_INTERFACE_SETTING;\r
\r
//\r
// An interface may have several settings. Use a\r
// fixed max number of settings to simplify code.\r
// It should sufice in most environments.\r
//\r
typedef struct {\r
  USB_INTERFACE_SETTING*        Settings[USB_MAX_INTERFACE_SETTING];\r
  UINTN                         NumOfSetting;\r
  UINTN                         ActiveIndex;  // Index of active setting\r
} USB_INTERFACE_DESC;\r
\r
typedef struct {\r
  EFI_USB_CONFIG_DESCRIPTOR     Desc;\r
  USB_INTERFACE_DESC            **Interfaces;\r
} USB_CONFIG_DESC;\r
\r
typedef struct {\r
  EFI_USB_DEVICE_DESCRIPTOR     Desc;\r
  USB_CONFIG_DESC               **Configs;\r
} USB_DEVICE_DESC;\r
\r
/**\r
  USB standard control transfer support routine. This\r
  function is used by USB device. It is possible that\r
  the device's interfaces are still waiting to be\r
  enumerated.\r
\r
  @param  UsbDev                The usb device.\r
  @param  Direction             The direction of data transfer.\r
  @param  Type                  Standard / class specific / vendor specific.\r
  @param  Target                The receiving target.\r
  @param  Request               Which request.\r
  @param  Value                 The wValue parameter of the request.\r
  @param  Index                 The wIndex parameter of the request.\r
  @param  Buf                   The buffer to receive data into / transmit from.\r
  @param  Length                The length of the buffer.\r
\r
  @retval EFI_SUCCESS           The control request is executed.\r
  @retval EFI_DEVICE_ERROR      Failed to execute the control transfer.\r
\r
**/\r
EFI_STATUS\r
UsbCtrlRequest (\r
  IN USB_DEVICE             *UsbDev,\r
  IN EFI_USB_DATA_DIRECTION Direction,\r
  IN UINTN                  Type,\r
  IN UINTN                  Target,\r
  IN UINTN                  Request,\r
  IN UINT16                 Value,\r
  IN UINT16                 Index,\r
  IN OUT VOID               *Buf,\r
  IN UINTN                  Length\r
  );\r
\r
/**\r
  Return the max packet size for endpoint zero. This function\r
  is the first function called to get descriptors during bus\r
  enumeration.\r
\r
  @param  UsbDev                The usb device.\r
\r
  @retval EFI_SUCCESS           The max packet size of endpoint zero is retrieved.\r
  @retval EFI_DEVICE_ERROR      Failed to retrieve it.\r
\r
**/\r
EFI_STATUS\r
UsbGetMaxPacketSize0 (\r
  IN USB_DEVICE           *UsbDev\r
  );\r
\r
/**\r
  Free a device descriptor with its configurations.\r
\r
  @param  DevDesc               The device descriptor.\r
\r
  @return None.\r
\r
**/\r
VOID\r
UsbFreeDevDesc (\r
  IN USB_DEVICE_DESC      *DevDesc\r
  );\r
\r
/**\r
  Retrieve the indexed string for the language. It requires two\r
  steps to get a string, first to get the string's length. Then\r
  the string itself.\r
\r
  @param  UsbDev                The usb device.\r
  @param  StringIndex           The index of the string to retrieve.\r
  @param  LangId                Language ID.\r
\r
  @return The created string descriptor or NULL.\r
\r
**/\r
EFI_USB_STRING_DESCRIPTOR*\r
UsbGetOneString (\r
  IN     USB_DEVICE       *UsbDev,\r
  IN     UINT8            StringIndex,\r
  IN     UINT16           LangId\r
  );\r
\r
/**\r
  Build the whole array of descriptors. This function must\r
  be called after UsbGetMaxPacketSize0 returns the max packet\r
  size correctly for endpoint 0.\r
\r
  @param  UsbDev                The Usb device.\r
\r
  @retval EFI_SUCCESS           The descriptor table is build.\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the descriptor.\r
\r
**/\r
EFI_STATUS\r
UsbBuildDescTable (\r
  IN USB_DEVICE           *UsbDev\r
  );\r
\r
/**\r
  Set the device's address.\r
\r
  @param  UsbDev                The device to set address to.\r
  @param  Address               The address to set.\r
\r
  @retval EFI_SUCCESS           The device is set to the address.\r
  @retval Others                Failed to set the device address.\r
\r
**/\r
EFI_STATUS\r
UsbSetAddress (\r
  IN USB_DEVICE           *UsbDev,\r
  IN UINT8                Address\r
  );\r
\r
/**\r
  Set the device's configuration. This function changes\r
  the device's internal state. UsbSelectConfig changes\r
  the Usb bus's internal state.\r
\r
  @param  UsbDev                The USB device to set configure to.\r
  @param  ConfigIndex           The configure index to set.\r
\r
  @retval EFI_SUCCESS           The device is configured now.\r
  @retval Others                Failed to set the device configure.\r
\r
**/\r
EFI_STATUS\r
UsbSetConfig (\r
  IN USB_DEVICE           *UsbDev,\r
  IN UINT8                ConfigIndex\r
  );\r
\r
/**\r
  Usb UsbIo interface to clear the feature. This is should\r
  only be used by HUB which is considered a device driver\r
  on top of the UsbIo interface.\r
\r
  @param  UsbIo                 The UsbIo interface.\r
  @param  Target                The target of the transfer: endpoint/device.\r
  @param  Feature               The feature to clear.\r
  @param  Index                 The wIndex parameter.\r
\r
  @retval EFI_SUCCESS           The device feature is cleared.\r
  @retval Others                Failed to clear the feature.\r
\r
**/\r
EFI_STATUS\r
UsbIoClearFeature (\r
  IN  EFI_USB_IO_PROTOCOL *UsbIo,\r
  IN  UINTN               Target,\r
  IN  UINT16              Feature,\r
  IN  UINT16              Index\r
  );\r
#endif\r