MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h

   1 /** @file
   2
   3     Manage Usb Descriptor List
   4
   5 Copyright (c) 2007 - 2014, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _USB_DESCRIPTOR_H_
  11 #define _USB_DESCRIPTOR_H_
  12
  13 #define USB_MAX_INTERFACE_SETTING  256
  14
  15 //
  16 // The RequestType in EFI_USB_DEVICE_REQUEST is composed of
  17 // three fields: One bit direction, 2 bit type, and 5 bit
  18 // target.
  19 //
  20 #define USB_REQUEST_TYPE(Dir, Type, Target) \
  21           ((UINT8)((((Dir) == EfiUsbDataIn ? 0x01 : 0) << 7) | (Type) | (Target)))
  22
  23 //
  24 // A common header for usb standard descriptor.
  25 // Each stand descriptor has a length and type.
  26 //
  27 #pragma pack(1)
  28 typedef struct {
  29   UINT8    Len;
  30   UINT8    Type;
  31 } USB_DESC_HEAD;
  32 #pragma pack()
  33
  34 //
  35 // Each USB device has a device descriptor. Each device may
  36 // have several configures. Each configure contains several
  37 // interfaces. Each interface may have several settings. Each
  38 // setting has several endpoints.
  39 //
  40 // EFI_USB_..._DESCRIPTOR must be the first member of the
  41 // structure.
  42 //
  43 typedef struct {
  44   EFI_USB_ENDPOINT_DESCRIPTOR    Desc;
  45   UINT8                          Toggle;
  46 } USB_ENDPOINT_DESC;
  47
  48 typedef struct {
  49   EFI_USB_INTERFACE_DESCRIPTOR    Desc;
  50   USB_ENDPOINT_DESC               **Endpoints;
  51 } USB_INTERFACE_SETTING;
  52
  53 //
  54 // An interface may have several settings. Use a
  55 // fixed max number of settings to simplify code.
  56 // It should sufice in most environments.
  57 //
  58 typedef struct {
  59   USB_INTERFACE_SETTING    *Settings[USB_MAX_INTERFACE_SETTING];
  60   UINTN                    NumOfSetting;
  61   UINTN                    ActiveIndex;       // Index of active setting
  62 } USB_INTERFACE_DESC;
  63
  64 typedef struct {
  65   EFI_USB_CONFIG_DESCRIPTOR    Desc;
  66   USB_INTERFACE_DESC           **Interfaces;
  67 } USB_CONFIG_DESC;
  68
  69 typedef struct {
  70   EFI_USB_DEVICE_DESCRIPTOR    Desc;
  71   USB_CONFIG_DESC              **Configs;
  72 } USB_DEVICE_DESC;
  73
  74 /**
  75   USB standard control transfer support routine. This
  76   function is used by USB device. It is possible that
  77   the device's interfaces are still waiting to be
  78   enumerated.
  79
  80   @param  UsbDev                The usb device.
  81   @param  Direction             The direction of data transfer.
  82   @param  Type                  Standard / class specific / vendor specific.
  83   @param  Target                The receiving target.
  84   @param  Request               Which request.
  85   @param  Value                 The wValue parameter of the request.
  86   @param  Index                 The wIndex parameter of the request.
  87   @param  Buf                   The buffer to receive data into / transmit from.
  88   @param  Length                The length of the buffer.
  89
  90   @retval EFI_SUCCESS           The control request is executed.
  91   @retval EFI_DEVICE_ERROR      Failed to execute the control transfer.
  92
  93 **/
  94 EFI_STATUS
  95 UsbCtrlRequest (
  96   IN USB_DEVICE              *UsbDev,
  97   IN EFI_USB_DATA_DIRECTION  Direction,
  98   IN UINTN                   Type,
  99   IN UINTN                   Target,
 100   IN UINTN                   Request,
 101   IN UINT16                  Value,
 102   IN UINT16                  Index,
 103   IN OUT VOID                *Buf,
 104   IN UINTN                   Length
 105   );
 106
 107 /**
 108   Return the max packet size for endpoint zero. This function
 109   is the first function called to get descriptors during bus
 110   enumeration.
 111
 112   @param  UsbDev                The usb device.
 113
 114   @retval EFI_SUCCESS           The max packet size of endpoint zero is retrieved.
 115   @retval EFI_DEVICE_ERROR      Failed to retrieve it.
 116
 117 **/
 118 EFI_STATUS
 119 UsbGetMaxPacketSize0 (
 120   IN USB_DEVICE  *UsbDev
 121   );
 122
 123 /**
 124   Free a device descriptor with its configurations.
 125
 126   @param  DevDesc               The device descriptor.
 127
 128   @return None.
 129
 130 **/
 131 VOID
 132 UsbFreeDevDesc (
 133   IN USB_DEVICE_DESC  *DevDesc
 134   );
 135
 136 /**
 137   Retrieve the indexed string for the language. It requires two
 138   steps to get a string, first to get the string's length. Then
 139   the string itself.
 140
 141   @param  UsbDev                The usb device.
 142   @param  StringIndex           The index of the string to retrieve.
 143   @param  LangId                Language ID.
 144
 145   @return The created string descriptor or NULL.
 146
 147 **/
 148 EFI_USB_STRING_DESCRIPTOR *
 149 UsbGetOneString (
 150   IN     USB_DEVICE  *UsbDev,
 151   IN     UINT8       StringIndex,
 152   IN     UINT16      LangId
 153   );
 154
 155 /**
 156   Build the whole array of descriptors. This function must
 157   be called after UsbGetMaxPacketSize0 returns the max packet
 158   size correctly for endpoint 0.
 159
 160   @param  UsbDev                The Usb device.
 161
 162   @retval EFI_SUCCESS           The descriptor table is build.
 163   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the descriptor.
 164
 165 **/
 166 EFI_STATUS
 167 UsbBuildDescTable (
 168   IN USB_DEVICE  *UsbDev
 169   );
 170
 171 /**
 172   Set the device's address.
 173
 174   @param  UsbDev                The device to set address to.
 175   @param  Address               The address to set.
 176
 177   @retval EFI_SUCCESS           The device is set to the address.
 178   @retval Others                Failed to set the device address.
 179
 180 **/
 181 EFI_STATUS
 182 UsbSetAddress (
 183   IN USB_DEVICE  *UsbDev,
 184   IN UINT8       Address
 185   );
 186
 187 /**
 188   Set the device's configuration. This function changes
 189   the device's internal state. UsbSelectConfig changes
 190   the Usb bus's internal state.
 191
 192   @param  UsbDev                The USB device to set configure to.
 193   @param  ConfigIndex           The configure index to set.
 194
 195   @retval EFI_SUCCESS           The device is configured now.
 196   @retval Others                Failed to set the device configure.
 197
 198 **/
 199 EFI_STATUS
 200 UsbSetConfig (
 201   IN USB_DEVICE  *UsbDev,
 202   IN UINT8       ConfigIndex
 203   );
 204
 205 /**
 206   Usb UsbIo interface to clear the feature. This is should
 207   only be used by HUB which is considered a device driver
 208   on top of the UsbIo interface.
 209
 210   @param  UsbIo                 The UsbIo interface.
 211   @param  Target                The target of the transfer: endpoint/device.
 212   @param  Feature               The feature to clear.
 213   @param  Index                 The wIndex parameter.
 214
 215   @retval EFI_SUCCESS           The device feature is cleared.
 216   @retval Others                Failed to clear the feature.
 217
 218 **/
 219 EFI_STATUS
 220 UsbIoClearFeature (
 221   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 222   IN  UINTN                Target,
 223   IN  UINT16               Feature,
 224   IN  UINT16               Index
 225   );
 226
 227 #endif