1 /** @file 2 3 Manage Usb Descriptor List 4 5 Copyright (c) 2007 - 2014, 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 256 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 UINTN 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 234