iPXE
Usb.h
Go to the documentation of this file.
00001 /** @file
00002   Support for USB 2.0 standard.
00003 
00004   Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>
00005   This program and the accompanying materials
00006   are licensed and made available under the terms and conditions of the BSD License
00007   which accompanies this distribution.  The full text of the license may be found at
00008   http://opensource.org/licenses/bsd-license.php
00009 
00010   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00011   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00012 
00013 **/
00014 
00015 #ifndef __USB_H__
00016 #define __USB_H__
00017 
00018 FILE_LICENCE ( BSD3 );
00019 
00020 //
00021 // Subset of Class and Subclass definitions from USB Specs
00022 //
00023 
00024 //
00025 // Usb mass storage class code
00026 //
00027 #define USB_MASS_STORE_CLASS    0x08
00028 
00029 //
00030 // Usb mass storage subclass code, specify the command set used.
00031 //
00032 #define USB_MASS_STORE_RBC      0x01 ///< Reduced Block Commands
00033 #define USB_MASS_STORE_8020I    0x02 ///< SFF-8020i, typically a CD/DVD device
00034 #define USB_MASS_STORE_QIC      0x03 ///< Typically a tape device
00035 #define USB_MASS_STORE_UFI      0x04 ///< Typically a floppy disk driver device
00036 #define USB_MASS_STORE_8070I    0x05 ///< SFF-8070i, typically a floppy disk driver device.
00037 #define USB_MASS_STORE_SCSI     0x06 ///< SCSI transparent command set
00038 
00039 //
00040 // Usb mass storage protocol code, specify the transport protocol
00041 //
00042 #define USB_MASS_STORE_CBI0     0x00 ///< CBI protocol with command completion interrupt
00043 #define USB_MASS_STORE_CBI1     0x01 ///< CBI protocol without command completion interrupt
00044 #define USB_MASS_STORE_BOT      0x50 ///< Bulk-Only Transport
00045 
00046 //
00047 // Standard device request and request type
00048 // USB 2.0 spec, Section 9.4
00049 //
00050 #define USB_DEV_GET_STATUS                  0x00
00051 #define USB_DEV_GET_STATUS_REQ_TYPE_D       0x80 // Receiver : Device
00052 #define USB_DEV_GET_STATUS_REQ_TYPE_I       0x81 // Receiver : Interface
00053 #define USB_DEV_GET_STATUS_REQ_TYPE_E       0x82 // Receiver : Endpoint
00054 
00055 #define USB_DEV_CLEAR_FEATURE               0x01
00056 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D    0x00 // Receiver : Device
00057 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I    0x01 // Receiver : Interface
00058 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E    0x02 // Receiver : Endpoint
00059 
00060 #define USB_DEV_SET_FEATURE                 0x03
00061 #define USB_DEV_SET_FEATURE_REQ_TYPE_D      0x00 // Receiver : Device
00062 #define USB_DEV_SET_FEATURE_REQ_TYPE_I      0x01 // Receiver : Interface
00063 #define USB_DEV_SET_FEATURE_REQ_TYPE_E      0x02 // Receiver : Endpoint
00064 
00065 #define USB_DEV_SET_ADDRESS                 0x05
00066 #define USB_DEV_SET_ADDRESS_REQ_TYPE        0x00
00067 
00068 #define USB_DEV_GET_DESCRIPTOR              0x06
00069 #define USB_DEV_GET_DESCRIPTOR_REQ_TYPE     0x80
00070 
00071 #define USB_DEV_SET_DESCRIPTOR              0x07
00072 #define USB_DEV_SET_DESCRIPTOR_REQ_TYPE     0x00
00073 
00074 #define USB_DEV_GET_CONFIGURATION           0x08
00075 #define USB_DEV_GET_CONFIGURATION_REQ_TYPE  0x80
00076 
00077 #define USB_DEV_SET_CONFIGURATION           0x09
00078 #define USB_DEV_SET_CONFIGURATION_REQ_TYPE  0x00
00079 
00080 #define USB_DEV_GET_INTERFACE               0x0A
00081 #define USB_DEV_GET_INTERFACE_REQ_TYPE      0x81
00082 
00083 #define USB_DEV_SET_INTERFACE               0x0B
00084 #define USB_DEV_SET_INTERFACE_REQ_TYPE      0x01
00085 
00086 #define USB_DEV_SYNCH_FRAME                 0x0C
00087 #define USB_DEV_SYNCH_FRAME_REQ_TYPE        0x82
00088 
00089 
00090 //
00091 // USB standard descriptors and reqeust
00092 //
00093 #pragma pack(1)
00094 
00095 ///
00096 /// Format of Setup Data for USB Device Requests
00097 /// USB 2.0 spec, Section 9.3
00098 ///
00099 typedef struct {
00100   UINT8           RequestType;
00101   UINT8           Request;
00102   UINT16          Value;
00103   UINT16          Index;
00104   UINT16          Length;
00105 } USB_DEVICE_REQUEST;
00106 
00107 ///
00108 /// Standard Device Descriptor
00109 /// USB 2.0 spec, Section 9.6.1
00110 ///
00111 typedef struct {
00112   UINT8           Length;
00113   UINT8           DescriptorType;
00114   UINT16          BcdUSB;
00115   UINT8           DeviceClass;
00116   UINT8           DeviceSubClass;
00117   UINT8           DeviceProtocol;
00118   UINT8           MaxPacketSize0;
00119   UINT16          IdVendor;
00120   UINT16          IdProduct;
00121   UINT16          BcdDevice;
00122   UINT8           StrManufacturer;
00123   UINT8           StrProduct;
00124   UINT8           StrSerialNumber;
00125   UINT8           NumConfigurations;
00126 } USB_DEVICE_DESCRIPTOR;
00127 
00128 ///
00129 /// Standard Configuration Descriptor
00130 /// USB 2.0 spec, Section 9.6.3
00131 ///
00132 typedef struct {
00133   UINT8           Length;
00134   UINT8           DescriptorType;
00135   UINT16          TotalLength;
00136   UINT8           NumInterfaces;
00137   UINT8           ConfigurationValue;
00138   UINT8           Configuration;
00139   UINT8           Attributes;
00140   UINT8           MaxPower;
00141 } USB_CONFIG_DESCRIPTOR;
00142 
00143 ///
00144 /// Standard Interface Descriptor
00145 /// USB 2.0 spec, Section 9.6.5
00146 ///
00147 typedef struct {
00148   UINT8           Length;
00149   UINT8           DescriptorType;
00150   UINT8           InterfaceNumber;
00151   UINT8           AlternateSetting;
00152   UINT8           NumEndpoints;
00153   UINT8           InterfaceClass;
00154   UINT8           InterfaceSubClass;
00155   UINT8           InterfaceProtocol;
00156   UINT8           Interface;
00157 } USB_INTERFACE_DESCRIPTOR;
00158 
00159 ///
00160 /// Standard Endpoint Descriptor
00161 /// USB 2.0 spec, Section 9.6.6
00162 ///
00163 typedef struct {
00164   UINT8           Length;
00165   UINT8           DescriptorType;
00166   UINT8           EndpointAddress;
00167   UINT8           Attributes;
00168   UINT16          MaxPacketSize;
00169   UINT8           Interval;
00170 } USB_ENDPOINT_DESCRIPTOR;
00171 
00172 ///
00173 /// UNICODE String Descriptor
00174 /// USB 2.0 spec, Section 9.6.7
00175 ///
00176 typedef struct {
00177   UINT8           Length;
00178   UINT8           DescriptorType;
00179   CHAR16          String[1];
00180 } EFI_USB_STRING_DESCRIPTOR;
00181 
00182 #pragma pack()
00183 
00184 
00185 typedef enum {
00186   //
00187   // USB request type
00188   //
00189   USB_REQ_TYPE_STANDARD   = (0x00 << 5),
00190   USB_REQ_TYPE_CLASS      = (0x01 << 5),
00191   USB_REQ_TYPE_VENDOR     = (0x02 << 5),
00192 
00193   //
00194   // Standard control transfer request type, or the value
00195   // to fill in EFI_USB_DEVICE_REQUEST.Request
00196   //
00197   USB_REQ_GET_STATUS      = 0x00,
00198   USB_REQ_CLEAR_FEATURE   = 0x01,
00199   USB_REQ_SET_FEATURE     = 0x03,
00200   USB_REQ_SET_ADDRESS     = 0x05,
00201   USB_REQ_GET_DESCRIPTOR  = 0x06,
00202   USB_REQ_SET_DESCRIPTOR  = 0x07,
00203   USB_REQ_GET_CONFIG      = 0x08,
00204   USB_REQ_SET_CONFIG      = 0x09,
00205   USB_REQ_GET_INTERFACE   = 0x0A,
00206   USB_REQ_SET_INTERFACE   = 0x0B,
00207   USB_REQ_SYNCH_FRAME     = 0x0C,
00208 
00209   //
00210   // Usb control transfer target
00211   //
00212   USB_TARGET_DEVICE       = 0,
00213   USB_TARGET_INTERFACE    = 0x01,
00214   USB_TARGET_ENDPOINT     = 0x02,
00215   USB_TARGET_OTHER        = 0x03,
00216 
00217   //
00218   // USB Descriptor types
00219   //
00220   USB_DESC_TYPE_DEVICE    = 0x01,
00221   USB_DESC_TYPE_CONFIG    = 0x02,
00222   USB_DESC_TYPE_STRING    = 0x03,
00223   USB_DESC_TYPE_INTERFACE = 0x04,
00224   USB_DESC_TYPE_ENDPOINT  = 0x05,
00225   USB_DESC_TYPE_HID       = 0x21,
00226   USB_DESC_TYPE_REPORT    = 0x22,
00227 
00228   //
00229   // Features to be cleared by CLEAR_FEATURE requests
00230   //
00231   USB_FEATURE_ENDPOINT_HALT = 0,
00232 
00233   //
00234   // USB endpoint types: 00: control, 01: isochronous, 10: bulk, 11: interrupt
00235   //
00236   USB_ENDPOINT_CONTROL    = 0x00,
00237   USB_ENDPOINT_ISO        = 0x01,
00238   USB_ENDPOINT_BULK       = 0x02,
00239   USB_ENDPOINT_INTERRUPT  = 0x03,
00240 
00241   USB_ENDPOINT_TYPE_MASK  = 0x03,
00242   USB_ENDPOINT_DIR_IN     = 0x80,
00243 
00244   //
00245   //Use 200 ms to increase the error handling response time
00246   //
00247   EFI_USB_INTERRUPT_DELAY = 2000000
00248 } USB_TYPES_DEFINITION;
00249 
00250 
00251 //
00252 // HID constants definition, see Device Class Definition
00253 // for Human Interface Devices (HID) rev1.11
00254 //
00255 
00256 //
00257 // HID standard GET_DESCRIPTOR request.
00258 //
00259 #define USB_HID_GET_DESCRIPTOR_REQ_TYPE  0x81
00260 
00261 //
00262 // HID specific requests.
00263 //
00264 #define USB_HID_CLASS_GET_REQ_TYPE       0xa1
00265 #define USB_HID_CLASS_SET_REQ_TYPE       0x21
00266 
00267 //
00268 // HID report item format
00269 //
00270 #define HID_ITEM_FORMAT_SHORT 0
00271 #define HID_ITEM_FORMAT_LONG  1
00272 
00273 //
00274 // Special tag indicating long items
00275 //
00276 #define HID_ITEM_TAG_LONG 15
00277 
00278 //
00279 // HID report descriptor item type (prefix bit 2,3)
00280 //
00281 #define HID_ITEM_TYPE_MAIN      0
00282 #define HID_ITEM_TYPE_GLOBAL    1
00283 #define HID_ITEM_TYPE_LOCAL     2
00284 #define HID_ITEM_TYPE_RESERVED  3
00285 
00286 //
00287 // HID report descriptor main item tags
00288 //
00289 #define HID_MAIN_ITEM_TAG_INPUT             8
00290 #define HID_MAIN_ITEM_TAG_OUTPUT            9
00291 #define HID_MAIN_ITEM_TAG_FEATURE           11
00292 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION  10
00293 #define HID_MAIN_ITEM_TAG_END_COLLECTION    12
00294 
00295 //
00296 // HID report descriptor main item contents
00297 //
00298 #define HID_MAIN_ITEM_CONSTANT      0x001
00299 #define HID_MAIN_ITEM_VARIABLE      0x002
00300 #define HID_MAIN_ITEM_RELATIVE      0x004
00301 #define HID_MAIN_ITEM_WRAP          0x008
00302 #define HID_MAIN_ITEM_NONLINEAR     0x010
00303 #define HID_MAIN_ITEM_NO_PREFERRED  0x020
00304 #define HID_MAIN_ITEM_NULL_STATE    0x040
00305 #define HID_MAIN_ITEM_VOLATILE      0x080
00306 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100
00307 
00308 //
00309 // HID report descriptor collection item types
00310 //
00311 #define HID_COLLECTION_PHYSICAL     0
00312 #define HID_COLLECTION_APPLICATION  1
00313 #define HID_COLLECTION_LOGICAL      2
00314 
00315 //
00316 // HID report descriptor global item tags
00317 //
00318 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE        0
00319 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM   1
00320 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM   2
00321 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM  3
00322 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM  4
00323 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT     5
00324 #define HID_GLOBAL_ITEM_TAG_UNIT              6
00325 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE       7
00326 #define HID_GLOBAL_ITEM_TAG_REPORT_ID         8
00327 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT      9
00328 #define HID_GLOBAL_ITEM_TAG_PUSH              10
00329 #define HID_GLOBAL_ITEM_TAG_POP               11
00330 
00331 //
00332 // HID report descriptor local item tags
00333 //
00334 #define HID_LOCAL_ITEM_TAG_USAGE              0
00335 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM      1
00336 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM      2
00337 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX   3
00338 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4
00339 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5
00340 #define HID_LOCAL_ITEM_TAG_STRING_INDEX       7
00341 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM     8
00342 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM     9
00343 #define HID_LOCAL_ITEM_TAG_DELIMITER          10
00344 
00345 //
00346 // HID report types
00347 //
00348 #define HID_INPUT_REPORT    1
00349 #define HID_OUTPUT_REPORT   2
00350 #define HID_FEATURE_REPORT  3
00351 
00352 //
00353 // HID class protocol request
00354 //
00355 #define EFI_USB_GET_REPORT_REQUEST    0x01
00356 #define EFI_USB_GET_IDLE_REQUEST      0x02
00357 #define EFI_USB_GET_PROTOCOL_REQUEST  0x03
00358 #define EFI_USB_SET_REPORT_REQUEST    0x09
00359 #define EFI_USB_SET_IDLE_REQUEST      0x0a
00360 #define EFI_USB_SET_PROTOCOL_REQUEST  0x0b
00361 
00362 #pragma pack(1)
00363 ///
00364 /// Descriptor header for Report/Physical Descriptors
00365 /// HID 1.1, section 6.2.1
00366 ///
00367 typedef struct hid_class_descriptor {
00368   UINT8   DescriptorType;
00369   UINT16  DescriptorLength;
00370 } EFI_USB_HID_CLASS_DESCRIPTOR;
00371 
00372 ///
00373 /// The HID descriptor identifies the length and type
00374 /// of subordinate descriptors for a device.
00375 /// HID 1.1, section 6.2.1
00376 ///
00377 typedef struct hid_descriptor {
00378   UINT8                         Length;
00379   UINT8                         DescriptorType;
00380   UINT16                        BcdHID;
00381   UINT8                         CountryCode;
00382   UINT8                         NumDescriptors;
00383   EFI_USB_HID_CLASS_DESCRIPTOR  HidClassDesc[1];
00384 } EFI_USB_HID_DESCRIPTOR;
00385 
00386 #pragma pack()
00387 
00388 #endif