1 /** @file 2 Support for USB 2.0 standard. 3 4 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> 5 Copyright (c) 2024, American Megatrends International LLC. All rights reserved.<BR> 6 7 SPDX-License-Identifier: BSD-2-Clause-Patent 8 9 **/ 10 11 #ifndef __USB_H__ 12 #define __USB_H__ 13 14 // 15 // Subset of Class and Subclass definitions from USB Specs 16 // 17 18 // 19 // Usb mass storage class code 20 // 21 #define USB_MASS_STORE_CLASS 0x08 22 23 // 24 // Usb mass storage subclass code, specify the command set used. 25 // 26 #define USB_MASS_STORE_RBC 0x01 ///< Reduced Block Commands 27 #define USB_MASS_STORE_8020I 0x02 ///< SFF-8020i, typically a CD/DVD device 28 #define USB_MASS_STORE_QIC 0x03 ///< Typically a tape device 29 #define USB_MASS_STORE_UFI 0x04 ///< Typically a floppy disk driver device 30 #define USB_MASS_STORE_8070I 0x05 ///< SFF-8070i, typically a floppy disk driver device. 31 #define USB_MASS_STORE_SCSI 0x06 ///< SCSI transparent command set 32 33 // 34 // Usb mass storage protocol code, specify the transport protocol 35 // 36 #define USB_MASS_STORE_CBI0 0x00 ///< CBI protocol with command completion interrupt 37 #define USB_MASS_STORE_CBI1 0x01 ///< CBI protocol without command completion interrupt 38 #define USB_MASS_STORE_BOT 0x50 ///< Bulk-Only Transport 39 40 // 41 // Standard device request and request type 42 // USB 2.0 spec, Section 9.4 43 // 44 #define USB_DEV_GET_STATUS 0x00 45 #define USB_DEV_GET_STATUS_REQ_TYPE_D 0x80 // Receiver : Device 46 #define USB_DEV_GET_STATUS_REQ_TYPE_I 0x81 // Receiver : Interface 47 #define USB_DEV_GET_STATUS_REQ_TYPE_E 0x82 // Receiver : Endpoint 48 49 #define USB_DEV_CLEAR_FEATURE 0x01 50 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D 0x00 // Receiver : Device 51 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I 0x01 // Receiver : Interface 52 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E 0x02 // Receiver : Endpoint 53 54 #define USB_DEV_SET_FEATURE 0x03 55 #define USB_DEV_SET_FEATURE_REQ_TYPE_D 0x00 // Receiver : Device 56 #define USB_DEV_SET_FEATURE_REQ_TYPE_I 0x01 // Receiver : Interface 57 #define USB_DEV_SET_FEATURE_REQ_TYPE_E 0x02 // Receiver : Endpoint 58 59 #define USB_DEV_SET_ADDRESS 0x05 60 #define USB_DEV_SET_ADDRESS_REQ_TYPE 0x00 61 62 #define USB_DEV_GET_DESCRIPTOR 0x06 63 #define USB_DEV_GET_DESCRIPTOR_REQ_TYPE 0x80 64 65 #define USB_DEV_SET_DESCRIPTOR 0x07 66 #define USB_DEV_SET_DESCRIPTOR_REQ_TYPE 0x00 67 68 #define USB_DEV_GET_CONFIGURATION 0x08 69 #define USB_DEV_GET_CONFIGURATION_REQ_TYPE 0x80 70 71 #define USB_DEV_SET_CONFIGURATION 0x09 72 #define USB_DEV_SET_CONFIGURATION_REQ_TYPE 0x00 73 74 #define USB_DEV_GET_INTERFACE 0x0A 75 #define USB_DEV_GET_INTERFACE_REQ_TYPE 0x81 76 77 #define USB_DEV_SET_INTERFACE 0x0B 78 #define USB_DEV_SET_INTERFACE_REQ_TYPE 0x01 79 80 #define USB_DEV_SYNCH_FRAME 0x0C 81 #define USB_DEV_SYNCH_FRAME_REQ_TYPE 0x82 82 83 // 84 // USB standard descriptors and reqeust 85 // 86 #pragma pack(1) 87 88 /// 89 /// Format of Setup Data for USB Device Requests 90 /// USB 2.0 spec, Section 9.3 91 /// 92 typedef struct { 93 UINT8 RequestType; 94 UINT8 Request; 95 UINT16 Value; 96 UINT16 Index; 97 UINT16 Length; 98 } USB_DEVICE_REQUEST; 99 100 /// 101 /// Standard Device Descriptor 102 /// USB 2.0 spec, Section 9.6.1 103 /// 104 typedef struct { 105 UINT8 Length; 106 UINT8 DescriptorType; 107 UINT16 BcdUSB; 108 UINT8 DeviceClass; 109 UINT8 DeviceSubClass; 110 UINT8 DeviceProtocol; 111 UINT8 MaxPacketSize0; 112 UINT16 IdVendor; 113 UINT16 IdProduct; 114 UINT16 BcdDevice; 115 UINT8 StrManufacturer; 116 UINT8 StrProduct; 117 UINT8 StrSerialNumber; 118 UINT8 NumConfigurations; 119 } USB_DEVICE_DESCRIPTOR; 120 121 /// 122 /// Standard Configuration Descriptor 123 /// USB 2.0 spec, Section 9.6.3 124 /// 125 typedef struct { 126 UINT8 Length; 127 UINT8 DescriptorType; 128 UINT16 TotalLength; 129 UINT8 NumInterfaces; 130 UINT8 ConfigurationValue; 131 UINT8 Configuration; 132 UINT8 Attributes; 133 UINT8 MaxPower; 134 } USB_CONFIG_DESCRIPTOR; 135 136 /// 137 /// Standard Interface Association Descriptor 138 /// USB 3.0 spec, Section 9.6.4 139 /// 140 typedef struct { 141 UINT8 Length; 142 UINT8 DescriptorType; 143 UINT8 FirstInterface; 144 UINT8 InterfaceCount; 145 UINT8 FunctionClass; 146 UINT8 FunctionSubclass; 147 UINT8 FunctionProtocol; 148 UINT8 FunctionDescriptionStringIndex; 149 } USB_INTERFACE_ASSOCIATION_DESCRIPTOR; 150 151 /// 152 /// Standard Interface Descriptor 153 /// USB 2.0 spec, Section 9.6.5 154 /// 155 typedef struct { 156 UINT8 Length; 157 UINT8 DescriptorType; 158 UINT8 InterfaceNumber; 159 UINT8 AlternateSetting; 160 UINT8 NumEndpoints; 161 UINT8 InterfaceClass; 162 UINT8 InterfaceSubClass; 163 UINT8 InterfaceProtocol; 164 UINT8 Interface; 165 } USB_INTERFACE_DESCRIPTOR; 166 167 /// 168 /// Standard Endpoint Descriptor 169 /// USB 2.0 spec, Section 9.6.6 170 /// 171 typedef struct { 172 UINT8 Length; 173 UINT8 DescriptorType; 174 UINT8 EndpointAddress; 175 UINT8 Attributes; 176 UINT16 MaxPacketSize; 177 UINT8 Interval; 178 } USB_ENDPOINT_DESCRIPTOR; 179 180 /// 181 /// UNICODE String Descriptor 182 /// USB 2.0 spec, Section 9.6.7 183 /// 184 typedef struct { 185 UINT8 Length; 186 UINT8 DescriptorType; 187 CHAR16 String[1]; 188 } EFI_USB_STRING_DESCRIPTOR; 189 190 #pragma pack() 191 192 typedef enum { 193 // 194 // USB request type 195 // 196 USB_REQ_TYPE_STANDARD = (0x00 << 5), 197 USB_REQ_TYPE_CLASS = (0x01 << 5), 198 USB_REQ_TYPE_VENDOR = (0x02 << 5), 199 200 // 201 // Standard control transfer request type, or the value 202 // to fill in EFI_USB_DEVICE_REQUEST.Request 203 // 204 USB_REQ_GET_STATUS = 0x00, 205 USB_REQ_CLEAR_FEATURE = 0x01, 206 USB_REQ_SET_FEATURE = 0x03, 207 USB_REQ_SET_ADDRESS = 0x05, 208 USB_REQ_GET_DESCRIPTOR = 0x06, 209 USB_REQ_SET_DESCRIPTOR = 0x07, 210 USB_REQ_GET_CONFIG = 0x08, 211 USB_REQ_SET_CONFIG = 0x09, 212 USB_REQ_GET_INTERFACE = 0x0A, 213 USB_REQ_SET_INTERFACE = 0x0B, 214 USB_REQ_SYNCH_FRAME = 0x0C, 215 216 // 217 // Usb control transfer target 218 // 219 USB_TARGET_DEVICE = 0, 220 USB_TARGET_INTERFACE = 0x01, 221 USB_TARGET_ENDPOINT = 0x02, 222 USB_TARGET_OTHER = 0x03, 223 224 // 225 // USB Descriptor types 226 // 227 USB_DESC_TYPE_DEVICE = 0x01, 228 USB_DESC_TYPE_CONFIG = 0x02, 229 USB_DESC_TYPE_STRING = 0x03, 230 USB_DESC_TYPE_INTERFACE = 0x04, 231 USB_DESC_TYPE_ENDPOINT = 0x05, 232 USB_DESC_TYPE_INTERFACE_ASSOCIATION = 0x0b, 233 USB_DESC_TYPE_HID = 0x21, 234 USB_DESC_TYPE_REPORT = 0x22, 235 USB_DESC_TYPE_CS_INTERFACE = 0x24, 236 USB_DESC_TYPE_CS_ENDPOINT = 0x25, 237 238 // 239 // Features to be cleared by CLEAR_FEATURE requests 240 // 241 USB_FEATURE_ENDPOINT_HALT = 0, 242 243 // 244 // USB endpoint types: 00: control, 01: isochronous, 10: bulk, 11: interrupt 245 // 246 USB_ENDPOINT_CONTROL = 0x00, 247 USB_ENDPOINT_ISO = 0x01, 248 USB_ENDPOINT_BULK = 0x02, 249 USB_ENDPOINT_INTERRUPT = 0x03, 250 251 USB_ENDPOINT_TYPE_MASK = 0x03, 252 USB_ENDPOINT_DIR_IN = 0x80, 253 254 // 255 // Use 200 ms to increase the error handling response time 256 // 257 EFI_USB_INTERRUPT_DELAY = 2000000 258 } USB_TYPES_DEFINITION; 259 260 // 261 // HID constants definition, see Device Class Definition 262 // for Human Interface Devices (HID) rev1.11 263 // 264 265 // 266 // HID standard GET_DESCRIPTOR request. 267 // 268 #define USB_HID_GET_DESCRIPTOR_REQ_TYPE 0x81 269 270 // 271 // HID specific requests. 272 // 273 #define USB_HID_CLASS_GET_REQ_TYPE 0xa1 274 #define USB_HID_CLASS_SET_REQ_TYPE 0x21 275 276 // 277 // HID report item format 278 // 279 #define HID_ITEM_FORMAT_SHORT 0 280 #define HID_ITEM_FORMAT_LONG 1 281 282 // 283 // Special tag indicating long items 284 // 285 #define HID_ITEM_TAG_LONG 15 286 287 // 288 // HID report descriptor item type (prefix bit 2,3) 289 // 290 #define HID_ITEM_TYPE_MAIN 0 291 #define HID_ITEM_TYPE_GLOBAL 1 292 #define HID_ITEM_TYPE_LOCAL 2 293 #define HID_ITEM_TYPE_RESERVED 3 294 295 // 296 // HID report descriptor main item tags 297 // 298 #define HID_MAIN_ITEM_TAG_INPUT 8 299 #define HID_MAIN_ITEM_TAG_OUTPUT 9 300 #define HID_MAIN_ITEM_TAG_FEATURE 11 301 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION 10 302 #define HID_MAIN_ITEM_TAG_END_COLLECTION 12 303 304 // 305 // HID report descriptor main item contents 306 // 307 #define HID_MAIN_ITEM_CONSTANT 0x001 308 #define HID_MAIN_ITEM_VARIABLE 0x002 309 #define HID_MAIN_ITEM_RELATIVE 0x004 310 #define HID_MAIN_ITEM_WRAP 0x008 311 #define HID_MAIN_ITEM_NONLINEAR 0x010 312 #define HID_MAIN_ITEM_NO_PREFERRED 0x020 313 #define HID_MAIN_ITEM_NULL_STATE 0x040 314 #define HID_MAIN_ITEM_VOLATILE 0x080 315 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100 316 317 // 318 // HID report descriptor collection item types 319 // 320 #define HID_COLLECTION_PHYSICAL 0 321 #define HID_COLLECTION_APPLICATION 1 322 #define HID_COLLECTION_LOGICAL 2 323 324 // 325 // HID report descriptor global item tags 326 // 327 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE 0 328 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM 1 329 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM 2 330 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM 3 331 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM 4 332 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT 5 333 #define HID_GLOBAL_ITEM_TAG_UNIT 6 334 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE 7 335 #define HID_GLOBAL_ITEM_TAG_REPORT_ID 8 336 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT 9 337 #define HID_GLOBAL_ITEM_TAG_PUSH 10 338 #define HID_GLOBAL_ITEM_TAG_POP 11 339 340 // 341 // HID report descriptor local item tags 342 // 343 #define HID_LOCAL_ITEM_TAG_USAGE 0 344 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM 1 345 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM 2 346 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX 3 347 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4 348 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5 349 #define HID_LOCAL_ITEM_TAG_STRING_INDEX 7 350 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM 8 351 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM 9 352 #define HID_LOCAL_ITEM_TAG_DELIMITER 10 353 354 // 355 // HID report types 356 // 357 #define HID_INPUT_REPORT 1 358 #define HID_OUTPUT_REPORT 2 359 #define HID_FEATURE_REPORT 3 360 361 // 362 // HID class protocol request 363 // 364 #define EFI_USB_GET_REPORT_REQUEST 0x01 365 #define EFI_USB_GET_IDLE_REQUEST 0x02 366 #define EFI_USB_GET_PROTOCOL_REQUEST 0x03 367 #define EFI_USB_SET_REPORT_REQUEST 0x09 368 #define EFI_USB_SET_IDLE_REQUEST 0x0a 369 #define EFI_USB_SET_PROTOCOL_REQUEST 0x0b 370 371 #pragma pack(1) 372 /// 373 /// Descriptor header for Report/Physical Descriptors 374 /// HID 1.1, section 6.2.1 375 /// 376 typedef struct hid_class_descriptor { 377 UINT8 DescriptorType; 378 UINT16 DescriptorLength; 379 } EFI_USB_HID_CLASS_DESCRIPTOR; 380 381 /// 382 /// The HID descriptor identifies the length and type 383 /// of subordinate descriptors for a device. 384 /// HID 1.1, section 6.2.1 385 /// 386 typedef struct hid_descriptor { 387 UINT8 Length; 388 UINT8 DescriptorType; 389 UINT16 BcdHID; 390 UINT8 CountryCode; 391 UINT8 NumDescriptors; 392 EFI_USB_HID_CLASS_DESCRIPTOR HidClassDesc[1]; 393 } EFI_USB_HID_DESCRIPTOR; 394 395 #pragma pack() 396 397 #endif 398