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