MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h

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