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