MdeModulePkg/Bus/Usb/UsbBotPei/PeiUsbLib.h

   1 /** @file
   2 Common Libarary  for PEI USB.
   3
   4 Copyright (c) 1999 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions
   8 of the BSD License which accompanies this distribution.  The
   9 full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef _PEI_USB_LIB_H_
  18 #define _PEI_USB_LIB_H_
  19 //
  20 // Standard device request and request type
  21 // By [Spec-USB20/Chapter-9.4]
  22 //
  23 #define USB_DEV_GET_STATUS                  0x00
  24 #define USB_DEV_GET_STATUS_REQ_TYPE_D       0x80 // Receiver : Device
  25 #define USB_DEV_GET_STATUS_REQ_TYPE_I       0x81 // Receiver : Interface
  26 #define USB_DEV_GET_STATUS_REQ_TYPE_E       0x82 // Receiver : Endpoint
  27
  28 #define USB_DEV_CLEAR_FEATURE               0x01
  29 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D    0x00 // Receiver : Device
  30 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I    0x01 // Receiver : Interface
  31 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E    0x02 // Receiver : Endpoint
  32
  33 #define USB_DEV_SET_FEATURE                 0x03
  34 #define USB_DEV_SET_FEATURE_REQ_TYPE_D      0x00 // Receiver : Device
  35 #define USB_DEV_SET_FEATURE_REQ_TYPE_I      0x01 // Receiver : Interface
  36 #define USB_DEV_SET_FEATURE_REQ_TYPE_E      0x02 // Receiver : Endpoint
  37
  38 #define USB_DEV_SET_ADDRESS                 0x05
  39 #define USB_DEV_SET_ADDRESS_REQ_TYPE        0x00
  40
  41 #define USB_DEV_GET_DESCRIPTOR              0x06
  42 #define USB_DEV_GET_DESCRIPTOR_REQ_TYPE     0x80
  43
  44 #define USB_DEV_SET_DESCRIPTOR              0x07
  45 #define USB_DEV_SET_DESCRIPTOR_REQ_TYPE     0x00
  46
  47 #define USB_DEV_GET_CONFIGURATION           0x08
  48 #define USB_DEV_GET_CONFIGURATION_REQ_TYPE  0x80
  49
  50 #define USB_DEV_SET_CONFIGURATION           0x09
  51 #define USB_DEV_SET_CONFIGURATION_REQ_TYPE  0x00
  52
  53 #define USB_DEV_GET_INTERFACE               0x0A
  54 #define USB_DEV_GET_INTERFACE_REQ_TYPE      0x81
  55
  56 #define USB_DEV_SET_INTERFACE               0x0B
  57 #define USB_DEV_SET_INTERFACE_REQ_TYPE      0x01
  58
  59 #define USB_DEV_SYNCH_FRAME                 0x0C
  60 #define USB_DEV_SYNCH_FRAME_REQ_TYPE        0x82
  61
  62 //
  63 // USB Descriptor types
  64 //
  65 #define USB_DT_DEVICE     0x01
  66 #define USB_DT_CONFIG     0x02
  67 #define USB_DT_STRING     0x03
  68 #define USB_DT_INTERFACE  0x04
  69 #define USB_DT_ENDPOINT   0x05
  70 #define USB_DT_HUB        0x29
  71 #define USB_DT_HID        0x21
  72
  73 //
  74 // USB request type
  75 //
  76 #define USB_TYPE_STANDARD (0x00 << 5)
  77 #define USB_TYPE_CLASS    (0x01 << 5)
  78 #define USB_TYPE_VENDOR   (0x02 << 5)
  79 #define USB_TYPE_RESERVED (0x03 << 5)
  80
  81 //
  82 // USB request targer device
  83 //
  84 #define USB_RECIP_DEVICE    0x00
  85 #define USB_RECIP_INTERFACE 0x01
  86 #define USB_RECIP_ENDPOINT  0x02
  87 #define USB_RECIP_OTHER     0x03
  88
  89 typedef enum {
  90   EfiUsbEndpointHalt,
  91   EfiUsbDeviceRemoteWakeup
  92 } EFI_USB_STANDARD_FEATURE_SELECTOR;
  93
  94 //
  95 // Usb Data recipient type
  96 //
  97 typedef enum {
  98   EfiUsbDevice,
  99   EfiUsbInterface,
 100   EfiUsbEndpoint
 101 } EFI_USB_RECIPIENT;
 102
 103 /**
 104   Get a given usb descriptor.
 105
 106   @param  PeiServices        General-purpose services that are available to every PEIM.
 107   @param  UsbIoPpi           Indicates the PEI_USB_IO_PPI instance.
 108   @param  Value              Request Value.
 109   @param  Index              Request Index.
 110   @param  DescriptorLength   Request descriptor Length.
 111   @param  Descriptor         Request descriptor.
 112
 113
 114   @retval EFI_SUCCESS       Usb descriptor is obtained successfully.
 115   @retval EFI_DEVICE_ERROR  Cannot get the usb descriptor due to a hardware error.
 116   @retval Others            Other failure occurs.
 117
 118 **/
 119 EFI_STATUS
 120 PeiUsbGetDescriptor (
 121   IN  EFI_PEI_SERVICES         **PeiServices,
 122   IN  PEI_USB_IO_PPI           *UsbIoPpi,
 123   IN  UINT16                   Value,
 124   IN  UINT16                   Index,
 125   IN  UINT16                   DescriptorLength,
 126   OUT VOID                     *Descriptor
 127   );
 128
 129 /**
 130   Set a usb device with a specified address.
 131
 132   @param  PeiServices        General-purpose services that are available to every PEIM.
 133   @param  UsbIoPpi           Indicates the PEI_USB_IO_PPI instance.
 134   @param  AddressValue       The address to assign.
 135
 136   @retval EFI_SUCCESS        Usb device address is set successfully.
 137   @retval EFI_DEVICE_ERROR   Cannot set the usb address due to a hardware error.
 138   @retval Others             Other failure occurs.
 139
 140 **/
 141 EFI_STATUS
 142 PeiUsbSetDeviceAddress (
 143   IN EFI_PEI_SERVICES         **PeiServices,
 144   IN PEI_USB_IO_PPI           *UsbIoPpi,
 145   IN UINT16                   AddressValue
 146   );
 147
 148 /**
 149   Clear a given usb feature.
 150
 151   @param  PeiServices       General-purpose services that are available to every PEIM.
 152   @param  UsbIoPpi          Indicates the PEI_USB_IO_PPI instance.
 153   @param  Recipient         The recipient of ClearFeature Request, should be one of Device/Interface/Endpoint.
 154   @param  Value             Request Value.
 155   @param  Target            Request Index.
 156
 157   @retval EFI_SUCCESS       Usb feature is cleared successfully.
 158   @retval EFI_DEVICE_ERROR  Cannot clear the usb feature due to a hardware error.
 159   @retval Others            Other failure occurs.
 160
 161 **/
 162 EFI_STATUS
 163 PeiUsbClearDeviceFeature (
 164   IN EFI_PEI_SERVICES         **PeiServices,
 165   IN PEI_USB_IO_PPI           *UsbIoPpi,
 166   IN EFI_USB_RECIPIENT        Recipient,
 167   IN UINT16                   Value,
 168   IN UINT16                   Target
 169   );
 170
 171 /**
 172   Configure a usb device to Configuration 1.
 173
 174   @param  PeiServices        General-purpose services that are available to every PEIM.
 175   @param  UsbIoPpi           Indicates the PEI_USB_IO_PPI instance.
 176
 177   @retval EFI_SUCCESS        Usb device is set to use Configuration 1 successfully.
 178   @retval EFI_DEVICE_ERROR   Cannot set the usb device due to a hardware error.
 179   @retval Others             Other failure occurs.
 180
 181 **/
 182 EFI_STATUS
 183 PeiUsbSetConfiguration (
 184   IN EFI_PEI_SERVICES         **PeiServices,
 185   IN PEI_USB_IO_PPI           *UsbIoPpi
 186   );
 187
 188 /**
 189   Clear Endpoint Halt.
 190
 191   @param  PeiServices       General-purpose services that are available to every PEIM.
 192   @param  UsbIoPpi          Indicates the PEI_USB_IO_PPI instance.
 193   @param  EndpointAddress   The endpoint address.
 194
 195   @retval EFI_SUCCESS       Endpoint halt is cleared successfully.
 196   @retval EFI_DEVICE_ERROR  Cannot clear the endpoint halt status due to a hardware error.
 197   @retval Others            Other failure occurs.
 198
 199 **/
 200 EFI_STATUS
 201 PeiUsbClearEndpointHalt (
 202   IN EFI_PEI_SERVICES         **PeiServices,
 203   IN PEI_USB_IO_PPI           *UsbIoPpi,
 204   IN UINT8                    EndpointAddress
 205   );
 206
 207 /**
 208   Judge if the port is connected with a usb device or not.
 209
 210   @param  PortStatus  The usb port status gotten.
 211
 212   @retval TRUE        A usb device is connected with the port.
 213   @retval FALSE       No usb device is connected with the port.
 214
 215 **/
 216 BOOLEAN
 217 IsPortConnect (
 218   IN UINT16  PortStatus
 219   );
 220
 221 /**
 222   Judge if the port is connected with a low-speed usb device or not.
 223
 224   @param  PortStatus  The usb port status gotten.
 225
 226   @retval TRUE        A low-speed usb device is connected with the port.
 227   @retval FALSE       No low-speed usb device is connected with the port.
 228
 229 **/
 230 BOOLEAN
 231 IsPortLowSpeedDeviceAttached (
 232   IN UINT16  PortStatus
 233   );
 234
 235 /**
 236   Judge if the port is in "connection change" status or not.
 237
 238   @param  PortChangeStatus  The usb port change status gotten.
 239
 240   @retval TRUE              The port is in "connection change" status.
 241   @retval FALSE             The port is NOT in "connection change" status.
 242
 243 **/
 244 BOOLEAN
 245 IsPortConnectChange (
 246   IN UINT16  PortChangeStatus
 247   );
 248 #endif