MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h

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