Dr Andrew Scott G7VAV

My photo
 
June 2025
Mo Tu We Th Fr Sa Su
26 27 28 29 30 31 1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29
30 1 2 3 4 5 6


ch9.h
001: /*
002:  * This file holds USB constants and structures that are needed for
003:  * USB device APIs.  These are used by the USB device model, which is
004:  * defined in chapter 9 of the USB 2.0 specification and in the
005:  * Wireless USB 1.0 (spread around).  Linux has several APIs in C that
006:  * need these:
007:  *
008:  * - the master/host side Linux-USB kernel driver API;
009:  * - the "usbfs" user space API; and
010:  * - the Linux "gadget" slave/device/peripheral side driver API.
011:  *
012:  * USB 2.0 adds an additional "On The Go" (OTG) mode, which lets systems
013:  * act either as a USB master/host or as a USB slave/device.  That means
014:  * the master and slave side APIs benefit from working well together.
015:  *
016:  * There's also "Wireless USB", using low power short range radios for
017:  * peripheral interconnection but otherwise building on the USB framework.
018:  *
019:  * Note all descriptors are declared '__attribute__((packed))' so that:
020:  *
021:  * [a] they never get padded, either internally (USB spec writers
022:  *     probably handled that) or externally;
023:  *
024:  * [b] so that accessing bigger-than-a-bytes fields will never
025:  *     generate bus errors on any platform, even when the location of
026:  *     its descriptor inside a bundle isn't "naturally aligned", and
027:  *
028:  * [c] for consistency, removing all doubt even when it appears to
029:  *     someone that the two other points are non-issues for that
030:  *     particular descriptor type.
031:  */
032: 
033: #ifndef __LINUX_USB_CH9_H
034: #define __LINUX_USB_CH9_H
035: 
036: #include <linux/types.h>        /* __u8 etc */
037: #include <asm/byteorder.h>      /* le16_to_cpu */
038: 
039: /*-------------------------------------------------------------------------*/
040: 
041: /* CONTROL REQUEST SUPPORT */
042: 
043: /*
044:  * USB directions
045:  *
046:  * This bit flag is used in endpoint descriptors' bEndpointAddress field.
047:  * It's also one of three fields in control requests bRequestType.
048:  */
049: #define USB_DIR_OUT                     0               /* to device */
050: #define USB_DIR_IN                      0x80            /* to host */
051: 
052: /*
053:  * USB types, the second of three bRequestType fields
054:  */
055: #define USB_TYPE_MASK                   (0x03 << 5)
056: #define USB_TYPE_STANDARD               (0x00 << 5)
057: #define USB_TYPE_CLASS                  (0x01 << 5)
058: #define USB_TYPE_VENDOR                 (0x02 << 5)
059: #define USB_TYPE_RESERVED               (0x03 << 5)
060: 
061: /*
062:  * USB recipients, the third of three bRequestType fields
063:  */
064: #define USB_RECIP_MASK                  0x1f
065: #define USB_RECIP_DEVICE                0x00
066: #define USB_RECIP_INTERFACE             0x01
067: #define USB_RECIP_ENDPOINT              0x02
068: #define USB_RECIP_OTHER                 0x03
069: /* From Wireless USB 1.0 */
070: #define USB_RECIP_PORT                  0x04
071: #define USB_RECIP_RPIPE         0x05
072: 
073: /*
074:  * Standard requests, for the bRequest field of a SETUP packet.
075:  *
076:  * These are qualified by the bRequestType field, so that for example
077:  * TYPE_CLASS or TYPE_VENDOR specific feature flags could be retrieved
078:  * by a GET_STATUS request.
079:  */
080: #define USB_REQ_GET_STATUS              0x00
081: #define USB_REQ_CLEAR_FEATURE           0x01
082: #define USB_REQ_SET_FEATURE             0x03
083: #define USB_REQ_SET_ADDRESS             0x05
084: #define USB_REQ_GET_DESCRIPTOR          0x06
085: #define USB_REQ_SET_DESCRIPTOR          0x07
086: #define USB_REQ_GET_CONFIGURATION       0x08
087: #define USB_REQ_SET_CONFIGURATION       0x09
088: #define USB_REQ_GET_INTERFACE           0x0A
089: #define USB_REQ_SET_INTERFACE           0x0B
090: #define USB_REQ_SYNCH_FRAME             0x0C
091: 
092: #define USB_REQ_SET_ENCRYPTION          0x0D    /* Wireless USB */
093: #define USB_REQ_GET_ENCRYPTION          0x0E
094: #define USB_REQ_RPIPE_ABORT             0x0E
095: #define USB_REQ_SET_HANDSHAKE           0x0F
096: #define USB_REQ_RPIPE_RESET             0x0F
097: #define USB_REQ_GET_HANDSHAKE           0x10
098: #define USB_REQ_SET_CONNECTION          0x11
099: #define USB_REQ_SET_SECURITY_DATA       0x12
100: #define USB_REQ_GET_SECURITY_DATA       0x13
101: #define USB_REQ_SET_WUSB_DATA           0x14
102: #define USB_REQ_LOOPBACK_DATA_WRITE     0x15
103: #define USB_REQ_LOOPBACK_DATA_READ      0x16
104: #define USB_REQ_SET_INTERFACE_DS        0x17
105: 
106: /* The Link Power Management (LPM) ECN defines USB_REQ_TEST_AND_SET command,
107:  * used by hubs to put ports into a new L1 suspend state, except that it
108:  * forgot to define its number ...
109:  */
110: 
111: /*
112:  * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
113:  * are read as a bit array returned by USB_REQ_GET_STATUS.  (So there
114:  * are at most sixteen features of each type.)  Hubs may also support a
115:  * new USB_REQ_TEST_AND_SET_FEATURE to put ports into L1 suspend.
116:  */
117: #define USB_DEVICE_SELF_POWERED         0       /* (read only) */
118: #define USB_DEVICE_REMOTE_WAKEUP        1       /* dev may initiate wakeup */
119: #define USB_DEVICE_TEST_MODE            2       /* (wired high speed only) */
120: #define USB_DEVICE_BATTERY              2       /* (wireless) */
121: #define USB_DEVICE_B_HNP_ENABLE         3       /* (otg) dev may initiate HNP */
122: #define USB_DEVICE_WUSB_DEVICE          3       /* (wireless)*/
123: #define USB_DEVICE_A_HNP_SUPPORT        4       /* (otg) RH port supports HNP */
124: #define USB_DEVICE_A_ALT_HNP_SUPPORT    5       /* (otg) other RH port does */
125: #define USB_DEVICE_DEBUG_MODE           6       /* (special devices only) */
126: 
127: /*
128:  * Test Mode Selectors
129:  * See USB 2.0 spec Table 9-7
130:  */
131: #define TEST_J          1
132: #define TEST_K          2
133: #define TEST_SE0_NAK    3
134: #define TEST_PACKET     4
135: #define TEST_FORCE_EN   5
136: 
137: /*
138:  * New Feature Selectors as added by USB 3.0
139:  * See USB 3.0 spec Table 9-6
140:  */
141: #define USB_DEVICE_U1_ENABLE    48      /* dev may initiate U1 transition */
142: #define USB_DEVICE_U2_ENABLE    49      /* dev may initiate U2 transition */
143: #define USB_DEVICE_LTM_ENABLE   50      /* dev may send LTM */
144: #define USB_INTRF_FUNC_SUSPEND  0       /* function suspend */
145: 
146: #define USB_INTR_FUNC_SUSPEND_OPT_MASK  0xFF00
147: /*
148:  * Suspend Options, Table 9-7 USB 3.0 spec
149:  */
150: #define USB_INTRF_FUNC_SUSPEND_LP       (1 << (8 + 0))
151: #define USB_INTRF_FUNC_SUSPEND_RW       (1 << (8 + 1))
152: 
153: #define USB_ENDPOINT_HALT               0       /* IN/OUT will STALL */
154: 
155: /* Bit array elements as returned by the USB_REQ_GET_STATUS request. */
156: #define USB_DEV_STAT_U1_ENABLED         2       /* transition into U1 state */
157: #define USB_DEV_STAT_U2_ENABLED         3       /* transition into U2 state */
158: #define USB_DEV_STAT_LTM_ENABLED        4       /* Latency tolerance messages */
159: 
160: /**
161:  * struct usb_ctrlrequest - SETUP data for a USB device control request
162:  * @bRequestType: matches the USB bmRequestType field
163:  * @bRequest: matches the USB bRequest field
164:  * @wValue: matches the USB wValue field (le16 byte order)
165:  * @wIndex: matches the USB wIndex field (le16 byte order)
166:  * @wLength: matches the USB wLength field (le16 byte order)
167:  *
168:  * This structure is used to send control requests to a USB device.  It matches
169:  * the different fields of the USB 2.0 Spec section 9.3, table 9-2.  See the
170:  * USB spec for a fuller description of the different fields, and what they are
171:  * used for.
172:  *
173:  * Note that the driver for any interface can issue control requests.
174:  * For most devices, interfaces don't coordinate with each other, so
175:  * such requests may be made at any time.
176:  */
177: struct usb_ctrlrequest {
178:         __u8 bRequestType;
179:         __u8 bRequest;
180:         __le16 wValue;
181:         __le16 wIndex;
182:         __le16 wLength;
183: } __attribute__ ((packed));
184: 
185: /*-------------------------------------------------------------------------*/
186: 
187: /*
188:  * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or
189:  * (rarely) accepted by SET_DESCRIPTOR.
190:  *
191:  * Note that all multi-byte values here are encoded in little endian
192:  * byte order "on the wire".  Within the kernel and when exposed
193:  * through the Linux-USB APIs, they are not converted to cpu byte
194:  * order; it is the responsibility of the client code to do this.
195:  * The single exception is when device and configuration descriptors (but
196:  * not other descriptors) are read from usbfs (i.e. /proc/bus/usb/BBB/DDD);
197:  * in this case the fields are converted to host endianness by the kernel.
198:  */
199: 
200: /*
201:  * Descriptor types ... USB 2.0 spec table 9.5
202:  */
203: #define USB_DT_DEVICE                   0x01
204: #define USB_DT_CONFIG                   0x02
205: #define USB_DT_STRING                   0x03
206: #define USB_DT_INTERFACE                0x04
207: #define USB_DT_ENDPOINT                 0x05
208: #define USB_DT_DEVICE_QUALIFIER         0x06
209: #define USB_DT_OTHER_SPEED_CONFIG       0x07
210: #define USB_DT_INTERFACE_POWER          0x08
211: /* these are from a minor usb 2.0 revision (ECN) */
212: #define USB_DT_OTG                      0x09
213: #define USB_DT_DEBUG                    0x0a
214: #define USB_DT_INTERFACE_ASSOCIATION    0x0b
215: /* these are from the Wireless USB spec */
216: #define USB_DT_SECURITY                 0x0c
217: #define USB_DT_KEY                      0x0d
218: #define USB_DT_ENCRYPTION_TYPE          0x0e
219: #define USB_DT_BOS                      0x0f
220: #define USB_DT_DEVICE_CAPABILITY        0x10
221: #define USB_DT_WIRELESS_ENDPOINT_COMP   0x11
222: #define USB_DT_WIRE_ADAPTER             0x21
223: #define USB_DT_RPIPE                    0x22
224: #define USB_DT_CS_RADIO_CONTROL         0x23
225: /* From the T10 UAS specification */
226: #define USB_DT_PIPE_USAGE               0x24
227: /* From the USB 3.0 spec */
228: #define USB_DT_SS_ENDPOINT_COMP         0x30
229: 
230: /* Conventional codes for class-specific descriptors.  The convention is
231:  * defined in the USB "Common Class" Spec (3.11).  Individual class specs
232:  * are authoritative for their usage, not the "common class" writeup.
233:  */
234: #define USB_DT_CS_DEVICE                (USB_TYPE_CLASS | USB_DT_DEVICE)
235: #define USB_DT_CS_CONFIG                (USB_TYPE_CLASS | USB_DT_CONFIG)
236: #define USB_DT_CS_STRING                (USB_TYPE_CLASS | USB_DT_STRING)
237: #define USB_DT_CS_INTERFACE             (USB_TYPE_CLASS | USB_DT_INTERFACE)
238: #define USB_DT_CS_ENDPOINT              (USB_TYPE_CLASS | USB_DT_ENDPOINT)
239: 
240: /* All standard descriptors have these 2 fields at the beginning */
241: struct usb_descriptor_header {
242:         __u8  bLength;
243:         __u8  bDescriptorType;
244: } __attribute__ ((packed));
245: 
246: 
247: /*-------------------------------------------------------------------------*/
248: 
249: /* USB_DT_DEVICE: Device descriptor */
250: struct usb_device_descriptor {
251:         __u8  bLength;
252:         __u8  bDescriptorType;
253: 
254:         __le16 bcdUSB;
255:         __u8  bDeviceClass;
256:         __u8  bDeviceSubClass;
257:         __u8  bDeviceProtocol;
258:         __u8  bMaxPacketSize0;
259:         __le16 idVendor;
260:         __le16 idProduct;
261:         __le16 bcdDevice;
262:         __u8  iManufacturer;
263:         __u8  iProduct;
264:         __u8  iSerialNumber;
265:         __u8  bNumConfigurations;
266: } __attribute__ ((packed));
267: 
268: #define USB_DT_DEVICE_SIZE              18
269: 
270: 
271: /*
272:  * Device and/or Interface Class codes
273:  * as found in bDeviceClass or bInterfaceClass
274:  * and defined by www.usb.org documents
275:  */
276: #define USB_CLASS_PER_INTERFACE         0       /* for DeviceClass */
277: #define USB_CLASS_AUDIO                 1
278: #define USB_CLASS_COMM                  2
279: #define USB_CLASS_HID                   3
280: #define USB_CLASS_PHYSICAL              5
281: #define USB_CLASS_STILL_IMAGE           6
282: #define USB_CLASS_PRINTER               7
283: #define USB_CLASS_MASS_STORAGE          8
284: #define USB_CLASS_HUB                   9
285: #define USB_CLASS_CDC_DATA              0x0a
286: #define USB_CLASS_CSCID                 0x0b    /* chip+ smart card */
287: #define USB_CLASS_CONTENT_SEC           0x0d    /* content security */
288: #define USB_CLASS_VIDEO                 0x0e
289: #define USB_CLASS_WIRELESS_CONTROLLER   0xe0
290: #define USB_CLASS_MISC                  0xef
291: #define USB_CLASS_APP_SPEC              0xfe
292: #define USB_CLASS_VENDOR_SPEC           0xff
293: 
294: #define USB_SUBCLASS_VENDOR_SPEC        0xff
295: 
296: /*-------------------------------------------------------------------------*/
297: 
298: /* USB_DT_CONFIG: Configuration descriptor information.
299:  *
300:  * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
301:  * descriptor type is different.  Highspeed-capable devices can look
302:  * different depending on what speed they're currently running.  Only
303:  * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
304:  * descriptors.
305:  */
306: struct usb_config_descriptor {
307:         __u8  bLength;
308:         __u8  bDescriptorType;
309: 
310:         __le16 wTotalLength;
311:         __u8  bNumInterfaces;
312:         __u8  bConfigurationValue;
313:         __u8  iConfiguration;
314:         __u8  bmAttributes;
315:         __u8  bMaxPower;
316: } __attribute__ ((packed));
317: 
318: #define USB_DT_CONFIG_SIZE              9
319: 
320: /* from config descriptor bmAttributes */
321: #define USB_CONFIG_ATT_ONE              (1 << 7)        /* must be set */
322: #define USB_CONFIG_ATT_SELFPOWER        (1 << 6)        /* self powered */
323: #define USB_CONFIG_ATT_WAKEUP           (1 << 5)        /* can wakeup */
324: #define USB_CONFIG_ATT_BATTERY          (1 << 4)        /* battery powered */
325: 
326: /*-------------------------------------------------------------------------*/
327: 
328: /* USB_DT_STRING: String descriptor */
329: struct usb_string_descriptor {
330:         __u8  bLength;
331:         __u8  bDescriptorType;
332: 
333:         __le16 wData[1];                /* UTF-16LE encoded */
334: } __attribute__ ((packed));
335: 
336: /* note that "string" zero is special, it holds language codes that
337:  * the device supports, not Unicode characters.
338:  */
339: 
340: /*-------------------------------------------------------------------------*/
341: 
342: /* USB_DT_INTERFACE: Interface descriptor */
343: struct usb_interface_descriptor {
344:         __u8  bLength;
345:         __u8  bDescriptorType;
346: 
347:         __u8  bInterfaceNumber;
348:         __u8  bAlternateSetting;
349:         __u8  bNumEndpoints;
350:         __u8  bInterfaceClass;
351:         __u8  bInterfaceSubClass;
352:         __u8  bInterfaceProtocol;
353:         __u8  iInterface;
354: } __attribute__ ((packed));
355: 
356: #define USB_DT_INTERFACE_SIZE           9
357: 
358: /*-------------------------------------------------------------------------*/
359: 
360: /* USB_DT_ENDPOINT: Endpoint descriptor */
361: struct usb_endpoint_descriptor {
362:         __u8  bLength;
363:         __u8  bDescriptorType;
364: 
365:         __u8  bEndpointAddress;
366:         __u8  bmAttributes;
367:         __le16 wMaxPacketSize;
368:         __u8  bInterval;
369: 
370:         /* NOTE:  these two are _only_ in audio endpoints. */
371:         /* use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof. */
372:         __u8  bRefresh;
373:         __u8  bSynchAddress;
374: } __attribute__ ((packed));
375: 
376: #define USB_DT_ENDPOINT_SIZE            7
377: #define USB_DT_ENDPOINT_AUDIO_SIZE      9       /* Audio extension */
378: 
379: 
380: /*
381:  * Endpoints
382:  */
383: #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
384: #define USB_ENDPOINT_DIR_MASK           0x80
385: 
386: #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
387: #define USB_ENDPOINT_XFER_CONTROL       0
388: #define USB_ENDPOINT_XFER_ISOC          1
389: #define USB_ENDPOINT_XFER_BULK          2
390: #define USB_ENDPOINT_XFER_INT           3
391: #define USB_ENDPOINT_MAX_ADJUSTABLE     0x80
392: 
393: #define USB_ENDPOINT_SYNCTYPE           0x0c
394: #define USB_ENDPOINT_SYNC_NONE          (0 << 2)
395: #define USB_ENDPOINT_SYNC_ASYNC         (1 << 2)
396: #define USB_ENDPOINT_SYNC_ADAPTIVE      (2 << 2)
397: #define USB_ENDPOINT_SYNC_SYNC          (3 << 2)
398: 
399: #define USB_ENDPOINT_USAGE_MASK         0x30
400: #define USB_ENDPOINT_USAGE_DATA         0x00
401: #define USB_ENDPOINT_USAGE_FEEDBACK     0x10
402: #define USB_ENDPOINT_USAGE_IMPLICIT_FB  0x20    /* Implicit feedback Data endpoint */
403: 
404: /*-------------------------------------------------------------------------*/
405: 
406: /**
407:  * usb_endpoint_num - get the endpoint's number
408:  * @epd: endpoint to be checked
409:  *
410:  * Returns @epd's number: 0 to 15.
411:  */
412: static __inline__ int usb_endpoint_num(const struct usb_endpoint_descriptor *epd)
413: {
414:         return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
415: }
416: 
417: /**
418:  * usb_endpoint_type - get the endpoint's transfer type
419:  * @epd: endpoint to be checked
420:  *
421:  * Returns one of USB_ENDPOINT_XFER_{CONTROL, ISOC, BULK, INT} according
422:  * to @epd's transfer type.
423:  */
424: static __inline__ int usb_endpoint_type(const struct usb_endpoint_descriptor *epd)
425: {
426:         return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
427: }
428: 
429: /**
430:  * usb_endpoint_dir_in - check if the endpoint has IN direction
431:  * @epd: endpoint to be checked
432:  *
433:  * Returns true if the endpoint is of type IN, otherwise it returns false.
434:  */
435: static __inline__ int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
436: {
437:         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
438: }
439: 
440: /**
441:  * usb_endpoint_dir_out - check if the endpoint has OUT direction
442:  * @epd: endpoint to be checked
443:  *
444:  * Returns true if the endpoint is of type OUT, otherwise it returns false.
445:  */
446: static __inline__ int usb_endpoint_dir_out(
447:                                 const struct usb_endpoint_descriptor *epd)
448: {
449:         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
450: }
451: 
452: /**
453:  * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
454:  * @epd: endpoint to be checked
455:  *
456:  * Returns true if the endpoint is of type bulk, otherwise it returns false.
457:  */
458: static __inline__ int usb_endpoint_xfer_bulk(
459:                                 const struct usb_endpoint_descriptor *epd)
460: {
461:         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
462:                 USB_ENDPOINT_XFER_BULK);
463: }
464: 
465: /**
466:  * usb_endpoint_xfer_control - check if the endpoint has control transfer type
467:  * @epd: endpoint to be checked
468:  *
469:  * Returns true if the endpoint is of type control, otherwise it returns false.
470:  */
471: static __inline__ int usb_endpoint_xfer_control(
472:                                 const struct usb_endpoint_descriptor *epd)
473: {
474:         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
475:                 USB_ENDPOINT_XFER_CONTROL);
476: }
477: 
478: /**
479:  * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
480:  * @epd: endpoint to be checked
481:  *
482:  * Returns true if the endpoint is of type interrupt, otherwise it returns
483:  * false.
484:  */
485: static __inline__ int usb_endpoint_xfer_int(
486:                                 const struct usb_endpoint_descriptor *epd)
487: {
488:         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
489:                 USB_ENDPOINT_XFER_INT);
490: }
491: 
492: /**
493:  * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
494:  * @epd: endpoint to be checked
495:  *
496:  * Returns true if the endpoint is of type isochronous, otherwise it returns
497:  * false.
498:  */
499: static __inline__ int usb_endpoint_xfer_isoc(
500:                                 const struct usb_endpoint_descriptor *epd)
501: {
502:         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
503:                 USB_ENDPOINT_XFER_ISOC);
504: }
505: 
506: /**
507:  * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
508:  * @epd: endpoint to be checked
509:  *
510:  * Returns true if the endpoint has bulk transfer type and IN direction,
511:  * otherwise it returns false.
512:  */
513: static __inline__ int usb_endpoint_is_bulk_in(
514:                                 const struct usb_endpoint_descriptor *epd)
515: {
516:         return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd);
517: }
518: 
519: /**
520:  * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
521:  * @epd: endpoint to be checked
522:  *
523:  * Returns true if the endpoint has bulk transfer type and OUT direction,
524:  * otherwise it returns false.
525:  */
526: static __inline__ int usb_endpoint_is_bulk_out(
527:                                 const struct usb_endpoint_descriptor *epd)
528: {
529:         return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd);
530: }
531: 
532: /**
533:  * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
534:  * @epd: endpoint to be checked
535:  *
536:  * Returns true if the endpoint has interrupt transfer type and IN direction,
537:  * otherwise it returns false.
538:  */
539: static __inline__ int usb_endpoint_is_int_in(
540:                                 const struct usb_endpoint_descriptor *epd)
541: {
542:         return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd);
543: }
544: 
545: /**
546:  * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
547:  * @epd: endpoint to be checked
548:  *
549:  * Returns true if the endpoint has interrupt transfer type and OUT direction,
550:  * otherwise it returns false.
551:  */
552: static __inline__ int usb_endpoint_is_int_out(
553:                                 const struct usb_endpoint_descriptor *epd)
554: {
555:         return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd);
556: }
557: 
558: /**
559:  * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
560:  * @epd: endpoint to be checked
561:  *
562:  * Returns true if the endpoint has isochronous transfer type and IN direction,
563:  * otherwise it returns false.
564:  */
565: static __inline__ int usb_endpoint_is_isoc_in(
566:                                 const struct usb_endpoint_descriptor *epd)
567: {
568:         return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd);
569: }
570: 
571: /**
572:  * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
573:  * @epd: endpoint to be checked
574:  *
575:  * Returns true if the endpoint has isochronous transfer type and OUT direction,
576:  * otherwise it returns false.
577:  */
578: static __inline__ int usb_endpoint_is_isoc_out(
579:                                 const struct usb_endpoint_descriptor *epd)
580: {
581:         return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd);
582: }
583: 
584: /**
585:  * usb_endpoint_maxp - get endpoint's max packet size
586:  * @epd: endpoint to be checked
587:  *
588:  * Returns @epd's max packet
589:  */
590: static __inline__ int usb_endpoint_maxp(const struct usb_endpoint_descriptor *epd)
591: {
592:         return __le16_to_cpu(epd->wMaxPacketSize);
593: }
594: 
595: /*-------------------------------------------------------------------------*/
596: 
597: /* USB_DT_SS_ENDPOINT_COMP: SuperSpeed Endpoint Companion descriptor */
598: struct usb_ss_ep_comp_descriptor {
599:         __u8  bLength;
600:         __u8  bDescriptorType;
601: 
602:         __u8  bMaxBurst;
603:         __u8  bmAttributes;
604:         __le16 wBytesPerInterval;
605: } __attribute__ ((packed));
606: 
607: #define USB_DT_SS_EP_COMP_SIZE          6
608: 
609: /* Bits 4:0 of bmAttributes if this is a bulk endpoint */
610: static __inline__ int
611: usb_ss_max_streams(const struct usb_ss_ep_comp_descriptor *comp)
612: {
613:         int             max_streams;
614: 
615:         if (!comp)
616:                 return 0;
617: 
618:         max_streams = comp->bmAttributes & 0x1f;
619: 
620:         if (!max_streams)
621:                 return 0;
622: 
623:         max_streams = 1 << max_streams;
624: 
625:         return max_streams;
626: }
627: 
628: /* Bits 1:0 of bmAttributes if this is an isoc endpoint */
629: #define USB_SS_MULT(p)                  (1 + ((p) & 0x3))
630: 
631: /*-------------------------------------------------------------------------*/
632: 
633: /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
634: struct usb_qualifier_descriptor {
635:         __u8  bLength;
636:         __u8  bDescriptorType;
637: 
638:         __le16 bcdUSB;
639:         __u8  bDeviceClass;
640:         __u8  bDeviceSubClass;
641:         __u8  bDeviceProtocol;
642:         __u8  bMaxPacketSize0;
643:         __u8  bNumConfigurations;
644:         __u8  bRESERVED;
645: } __attribute__ ((packed));
646: 
647: 
648: /*-------------------------------------------------------------------------*/
649: 
650: /* USB_DT_OTG (from OTG 1.0a supplement) */
651: struct usb_otg_descriptor {
652:         __u8  bLength;
653:         __u8  bDescriptorType;
654: 
655:         __u8  bmAttributes;     /* support for HNP, SRP, etc */
656: } __attribute__ ((packed));
657: 
658: /* from usb_otg_descriptor.bmAttributes */
659: #define USB_OTG_SRP             (1 << 0)
660: #define USB_OTG_HNP             (1 << 1)        /* swap host/device roles */
661: 
662: /*-------------------------------------------------------------------------*/
663: 
664: /* USB_DT_DEBUG:  for special highspeed devices, replacing serial console */
665: struct usb_debug_descriptor {
666:         __u8  bLength;
667:         __u8  bDescriptorType;
668: 
669:         /* bulk endpoints with 8 byte maxpacket */
670:         __u8  bDebugInEndpoint;
671:         __u8  bDebugOutEndpoint;
672: } __attribute__((packed));
673: 
674: /*-------------------------------------------------------------------------*/
675: 
676: /* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */
677: struct usb_interface_assoc_descriptor {
678:         __u8  bLength;
679:         __u8  bDescriptorType;
680: 
681:         __u8  bFirstInterface;
682:         __u8  bInterfaceCount;
683:         __u8  bFunctionClass;
684:         __u8  bFunctionSubClass;
685:         __u8  bFunctionProtocol;
686:         __u8  iFunction;
687: } __attribute__ ((packed));
688: 
689: 
690: /*-------------------------------------------------------------------------*/
691: 
692: /* USB_DT_SECURITY:  group of wireless security descriptors, including
693:  * encryption types available for setting up a CC/association.
694:  */
695: struct usb_security_descriptor {
696:         __u8  bLength;
697:         __u8  bDescriptorType;
698: 
699:         __le16 wTotalLength;
700:         __u8  bNumEncryptionTypes;
701: } __attribute__((packed));
702: 
703: /*-------------------------------------------------------------------------*/
704: 
705: /* USB_DT_KEY:  used with {GET,SET}_SECURITY_DATA; only public keys
706:  * may be retrieved.
707:  */
708: struct usb_key_descriptor {
709:         __u8  bLength;
710:         __u8  bDescriptorType;
711: 
712:         __u8  tTKID[3];
713:         __u8  bReserved;
714:         __u8  bKeyData[0];
715: } __attribute__((packed));
716: 
717: /*-------------------------------------------------------------------------*/
718: 
719: /* USB_DT_ENCRYPTION_TYPE:  bundled in DT_SECURITY groups */
720: struct usb_encryption_descriptor {
721:         __u8  bLength;
722:         __u8  bDescriptorType;
723: 
724:         __u8  bEncryptionType;
725: #define USB_ENC_TYPE_UNSECURE           0
726: #define USB_ENC_TYPE_WIRED              1       /* non-wireless mode */
727: #define USB_ENC_TYPE_CCM_1              2       /* aes128/cbc session */
728: #define USB_ENC_TYPE_RSA_1              3       /* rsa3072/sha1 auth */
729:         __u8  bEncryptionValue;         /* use in SET_ENCRYPTION */
730:         __u8  bAuthKeyIndex;
731: } __attribute__((packed));
732: 
733: 
734: /*-------------------------------------------------------------------------*/
735: 
736: /* USB_DT_BOS:  group of device-level capabilities */
737: struct usb_bos_descriptor {
738:         __u8  bLength;
739:         __u8  bDescriptorType;
740: 
741:         __le16 wTotalLength;
742:         __u8  bNumDeviceCaps;
743: } __attribute__((packed));
744: 
745: #define USB_DT_BOS_SIZE         5
746: /*-------------------------------------------------------------------------*/
747: 
748: /* USB_DT_DEVICE_CAPABILITY:  grouped with BOS */
749: struct usb_dev_cap_header {
750:         __u8  bLength;
751:         __u8  bDescriptorType;
752:         __u8  bDevCapabilityType;
753: } __attribute__((packed));
754: 
755: #define USB_CAP_TYPE_WIRELESS_USB       1
756: 
757: struct usb_wireless_cap_descriptor {    /* Ultra Wide Band */
758:         __u8  bLength;
759:         __u8  bDescriptorType;
760:         __u8  bDevCapabilityType;
761: 
762:         __u8  bmAttributes;
763: #define USB_WIRELESS_P2P_DRD            (1 << 1)
764: #define USB_WIRELESS_BEACON_MASK        (3 << 2)
765: #define USB_WIRELESS_BEACON_SELF        (1 << 2)
766: #define USB_WIRELESS_BEACON_DIRECTED    (2 << 2)
767: #define USB_WIRELESS_BEACON_NONE        (3 << 2)
768:         __le16 wPHYRates;       /* bit rates, Mbps */
769: #define USB_WIRELESS_PHY_53             (1 << 0)        /* always set */
770: #define USB_WIRELESS_PHY_80             (1 << 1)
771: #define USB_WIRELESS_PHY_107            (1 << 2)        /* always set */
772: #define USB_WIRELESS_PHY_160            (1 << 3)
773: #define USB_WIRELESS_PHY_200            (1 << 4)        /* always set */
774: #define USB_WIRELESS_PHY_320            (1 << 5)
775: #define USB_WIRELESS_PHY_400            (1 << 6)
776: #define USB_WIRELESS_PHY_480            (1 << 7)
777:         __u8  bmTFITXPowerInfo; /* TFI power levels */
778:         __u8  bmFFITXPowerInfo; /* FFI power levels */
779:         __le16 bmBandGroup;
780:         __u8  bReserved;
781: } __attribute__((packed));
782: 
783: /* USB 2.0 Extension descriptor */
784: #define USB_CAP_TYPE_EXT                2
785: 
786: struct usb_ext_cap_descriptor {         /* Link Power Management */
787:         __u8  bLength;
788:         __u8  bDescriptorType;
789:         __u8  bDevCapabilityType;
790:         __le32 bmAttributes;
791: #define USB_LPM_SUPPORT                 (1 << 1)        /* supports LPM */
792: } __attribute__((packed));
793: 
794: #define USB_DT_USB_EXT_CAP_SIZE 7
795: 
796: /*
797:  * SuperSpeed USB Capability descriptor: Defines the set of SuperSpeed USB
798:  * specific device level capabilities
799:  */
800: #define         USB_SS_CAP_TYPE         3
801: struct usb_ss_cap_descriptor {          /* Link Power Management */
802:         __u8  bLength;
803:         __u8  bDescriptorType;
804:         __u8  bDevCapabilityType;
805:         __u8  bmAttributes;
806: #define USB_LTM_SUPPORT                 (1 << 1) /* supports LTM */
807:         __le16 wSpeedSupported;
808: #define USB_LOW_SPEED_OPERATION         (1)      /* Low speed operation */
809: #define USB_FULL_SPEED_OPERATION        (1 << 1) /* Full speed operation */
810: #define USB_HIGH_SPEED_OPERATION        (1 << 2) /* High speed operation */
811: #define USB_5GBPS_OPERATION             (1 << 3) /* Operation at 5Gbps */
812:         __u8  bFunctionalitySupport;
813:         __u8  bU1devExitLat;
814:         __le16 bU2DevExitLat;
815: } __attribute__((packed));
816: 
817: #define USB_DT_USB_SS_CAP_SIZE  10
818: 
819: /*
820:  * Container ID Capability descriptor: Defines the instance unique ID used to
821:  * identify the instance across all operating modes
822:  */
823: #define CONTAINER_ID_TYPE       4
824: struct usb_ss_container_id_descriptor {
825:         __u8  bLength;
826:         __u8  bDescriptorType;
827:         __u8  bDevCapabilityType;
828:         __u8  bReserved;
829:         __u8  ContainerID[16]; /* 128-bit number */
830: } __attribute__((packed));
831: 
832: #define USB_DT_USB_SS_CONTN_ID_SIZE     20
833: /*-------------------------------------------------------------------------*/
834: 
835: /* USB_DT_WIRELESS_ENDPOINT_COMP:  companion descriptor associated with
836:  * each endpoint descriptor for a wireless device
837:  */
838: struct usb_wireless_ep_comp_descriptor {
839:         __u8  bLength;
840:         __u8  bDescriptorType;
841: 
842:         __u8  bMaxBurst;
843:         __u8  bMaxSequence;
844:         __le16 wMaxStreamDelay;
845:         __le16 wOverTheAirPacketSize;
846:         __u8  bOverTheAirInterval;
847:         __u8  bmCompAttributes;
848: #define USB_ENDPOINT_SWITCH_MASK        0x03    /* in bmCompAttributes */
849: #define USB_ENDPOINT_SWITCH_NO          0
850: #define USB_ENDPOINT_SWITCH_SWITCH      1
851: #define USB_ENDPOINT_SWITCH_SCALE       2
852: } __attribute__((packed));
853: 
854: /*-------------------------------------------------------------------------*/
855: 
856: /* USB_REQ_SET_HANDSHAKE is a four-way handshake used between a wireless
857:  * host and a device for connection set up, mutual authentication, and
858:  * exchanging short lived session keys.  The handshake depends on a CC.
859:  */
860: struct usb_handshake {
861:         __u8 bMessageNumber;
862:         __u8 bStatus;
863:         __u8 tTKID[3];
864:         __u8 bReserved;
865:         __u8 CDID[16];
866:         __u8 nonce[16];
867:         __u8 MIC[8];
868: } __attribute__((packed));
869: 
870: /*-------------------------------------------------------------------------*/
871: 
872: /* USB_REQ_SET_CONNECTION modifies or revokes a connection context (CC).
873:  * A CC may also be set up using non-wireless secure channels (including
874:  * wired USB!), and some devices may support CCs with multiple hosts.
875:  */
876: struct usb_connection_context {
877:         __u8 CHID[16];          /* persistent host id */
878:         __u8 CDID[16];          /* device id (unique w/in host context) */
879:         __u8 CK[16];            /* connection key */
880: } __attribute__((packed));
881: 
882: /*-------------------------------------------------------------------------*/
883: 
884: /* USB 2.0 defines three speeds, here's how Linux identifies them */
885: 
886: enum usb_device_speed {
887:         USB_SPEED_UNKNOWN = 0,                  /* enumerating */
888:         USB_SPEED_LOW, USB_SPEED_FULL,          /* usb 1.1 */
889:         USB_SPEED_HIGH,                         /* usb 2.0 */
890:         USB_SPEED_WIRELESS,                     /* wireless (usb 2.5) */
891:         USB_SPEED_SUPER,                        /* usb 3.0 */
892: };
893: 
894: 
895: enum usb_device_state {
896:         /* NOTATTACHED isn't in the USB spec, and this state acts
897:          * the same as ATTACHED ... but it's clearer this way.
898:          */
899:         USB_STATE_NOTATTACHED = 0,
900: 
901:         /* chapter 9 and authentication (wireless) device states */
902:         USB_STATE_ATTACHED,
903:         USB_STATE_POWERED,                      /* wired */
904:         USB_STATE_RECONNECTING,                 /* auth */
905:         USB_STATE_UNAUTHENTICATED,              /* auth */
906:         USB_STATE_DEFAULT,                      /* limited function */
907:         USB_STATE_ADDRESS,
908:         USB_STATE_CONFIGURED,                   /* most functions */
909: 
910:         USB_STATE_SUSPENDED
911: 
912:         /* NOTE:  there are actually four different SUSPENDED
913:          * states, returning to POWERED, DEFAULT, ADDRESS, or
914:          * CONFIGURED respectively when SOF tokens flow again.
915:          * At this level there's no difference between L1 and L2
916:          * suspend states.  (L2 being original USB 1.1 suspend.)
917:          */
918: };
919: 
920: /*-------------------------------------------------------------------------*/
921: 
922: /*
923:  * As per USB compliance update, a device that is actively drawing
924:  * more than 100mA from USB must report itself as bus-powered in
925:  * the GetStatus(DEVICE) call.
926:  * http://compliance.usb.org/index.asp?UpdateFile=Electrical&Format=Standard#34
927:  */
928: #define USB_SELF_POWER_VBUS_MAX_DRAW            100
929: 
930: #endif /* __LINUX_USB_CH9_H */
931: 


for client (none)
© Andrew Scott 2006 - 2025,
All Rights Reserved
http://www.andrew-scott.uk/
Andrew Scott
http://www.andrew-scott.co.uk/