[PATCH] usb_set_interface: correct toggle reset
[opensuse:kernel.git] / include / linux / usb.h
1 #ifndef __LINUX_USB_H
2 #define __LINUX_USB_H
3
4 #include <linux/device.h>
5
6 /* USB constants */
7
8 /*
9  * Device and/or Interface Class codes
10  */
11 #define USB_CLASS_PER_INTERFACE         0       /* for DeviceClass */
12 #define USB_CLASS_AUDIO                 1
13 #define USB_CLASS_COMM                  2
14 #define USB_CLASS_HID                   3
15 #define USB_CLASS_PHYSICAL              5
16 #define USB_CLASS_STILL_IMAGE           6
17 #define USB_CLASS_PRINTER               7
18 #define USB_CLASS_MASS_STORAGE          8
19 #define USB_CLASS_HUB                   9
20 #define USB_CLASS_CDC_DATA              0x0a
21 #define USB_CLASS_CSCID         0x0b /* chip+ smart card */
22 #define USB_CLASS_CONTENT_SEC           0x0d /* content security */
23 #define USB_CLASS_APP_SPEC              0xfe
24 #define USB_CLASS_VENDOR_SPEC           0xff
25
26 /*
27  * USB types
28  */
29 #define USB_TYPE_MASK                   (0x03 << 5)
30 #define USB_TYPE_STANDARD               (0x00 << 5)
31 #define USB_TYPE_CLASS                  (0x01 << 5)
32 #define USB_TYPE_VENDOR                 (0x02 << 5)
33 #define USB_TYPE_RESERVED               (0x03 << 5)
34
35 /*
36  * USB recipients
37  */
38 #define USB_RECIP_MASK                  0x1f
39 #define USB_RECIP_DEVICE                0x00
40 #define USB_RECIP_INTERFACE             0x01
41 #define USB_RECIP_ENDPOINT              0x02
42 #define USB_RECIP_OTHER                 0x03
43
44 /*
45  * USB directions
46  */
47 #define USB_DIR_OUT                     0
48 #define USB_DIR_IN                      0x80
49
50 /*
51  * Endpoints
52  */
53 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
54 #define USB_ENDPOINT_DIR_MASK           0x80
55
56 #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
57 #define USB_ENDPOINT_XFER_CONTROL       0
58 #define USB_ENDPOINT_XFER_ISOC          1
59 #define USB_ENDPOINT_XFER_BULK          2
60 #define USB_ENDPOINT_XFER_INT           3
61
62 /*
63  * USB Packet IDs (PIDs)
64  */
65 #define USB_PID_UNDEF_0                        0xf0
66 #define USB_PID_OUT                            0xe1
67 #define USB_PID_ACK                            0xd2
68 #define USB_PID_DATA0                          0xc3
69 #define USB_PID_PING                           0xb4     /* USB 2.0 */
70 #define USB_PID_SOF                            0xa5
71 #define USB_PID_NYET                           0x96     /* USB 2.0 */
72 #define USB_PID_DATA2                          0x87     /* USB 2.0 */
73 #define USB_PID_SPLIT                          0x78     /* USB 2.0 */
74 #define USB_PID_IN                             0x69
75 #define USB_PID_NAK                            0x5a
76 #define USB_PID_DATA1                          0x4b
77 #define USB_PID_PREAMBLE                       0x3c     /* Token mode */
78 #define USB_PID_ERR                            0x3c     /* USB 2.0: handshake mode */
79 #define USB_PID_SETUP                          0x2d
80 #define USB_PID_STALL                          0x1e
81 #define USB_PID_MDATA                          0x0f     /* USB 2.0 */
82
83 /*
84  * Standard requests
85  */
86 #define USB_REQ_GET_STATUS              0x00
87 #define USB_REQ_CLEAR_FEATURE           0x01
88 #define USB_REQ_SET_FEATURE             0x03
89 #define USB_REQ_SET_ADDRESS             0x05
90 #define USB_REQ_GET_DESCRIPTOR          0x06
91 #define USB_REQ_SET_DESCRIPTOR          0x07
92 #define USB_REQ_GET_CONFIGURATION       0x08
93 #define USB_REQ_SET_CONFIGURATION       0x09
94 #define USB_REQ_GET_INTERFACE           0x0A
95 #define USB_REQ_SET_INTERFACE           0x0B
96 #define USB_REQ_SYNCH_FRAME             0x0C
97
98
99 #ifdef __KERNEL__
100
101 #include <linux/types.h>
102 #include <linux/ioctl.h>
103 #include <linux/version.h>
104 #include <linux/sched.h>
105 #include <linux/delay.h>
106 #include <linux/interrupt.h>    /* for in_interrupt() */
107 #include <linux/config.h>
108 #include <linux/list.h>
109
110 #define USB_MAJOR 180
111
112 static __inline__ void wait_ms(unsigned int ms)
113 {
114         if(!in_interrupt()) {
115                 current->state = TASK_UNINTERRUPTIBLE;
116                 schedule_timeout(1 + ms * HZ / 1000);
117         }
118         else
119                 mdelay(ms);
120 }
121
122 /**
123  * struct usb_ctrlrequest - structure used to make USB device control requests easier to create and decode
124  * @bRequestType: matches the USB bmRequestType field
125  * @bRequest: matches the USB bRequest field
126  * @wValue: matches the USB wValue field
127  * @wIndex: matches the USB wIndex field
128  * @wLength: matches the USB wLength field
129  *
130  * This structure is used to send control requests to a USB device.  It matches
131  * the different fields of the USB 2.0 Spec section 9.3, table 9-2.  See the
132  * USB spec for a fuller description of the different fields, and what they are
133  * used for.
134  */
135 struct usb_ctrlrequest {
136         __u8 bRequestType;
137         __u8 bRequest;
138         __u16 wValue;
139         __u16 wIndex;
140         __u16 wLength;
141 } __attribute__ ((packed));
142
143 /*
144  * USB device number allocation bitmap. There's one bitmap
145  * per USB tree.
146  */
147 struct usb_devmap {
148         unsigned long devicemap[128 / (8*sizeof(unsigned long))];
149 };
150
151 #define USB_MAXBUS              64
152
153 struct usb_busmap {
154         unsigned long busmap[USB_MAXBUS / (8*sizeof(unsigned long))];
155 };
156
157 struct usb_device;
158
159 /*-------------------------------------------------------------------------*/
160
161 /*
162  * Standard USB Descriptor support.
163  * Devices may also have class-specific or vendor-specific descriptors.
164  */
165
166 /*
167  * Descriptor types ... USB 2.0 spec table 9.5
168  */
169 #define USB_DT_DEVICE                   0x01
170 #define USB_DT_CONFIG                   0x02
171 #define USB_DT_STRING                   0x03
172 #define USB_DT_INTERFACE                0x04
173 #define USB_DT_ENDPOINT                 0x05
174 #define USB_DT_DEVICE_QUALIFIER         0x06
175 #define USB_DT_OTHER_SPEED_CONFIG       0x07
176 #define USB_DT_INTERFACE_POWER          0x08
177
178 // FIXME should be internal to hub driver
179 #define USB_DT_HUB                      (USB_TYPE_CLASS | 0x09)
180 #define USB_DT_HUB_NONVAR_SIZE          7
181
182 /*
183  * Descriptor sizes per descriptor type
184  */
185 #define USB_DT_DEVICE_SIZE              18
186 #define USB_DT_CONFIG_SIZE              9
187 #define USB_DT_INTERFACE_SIZE           9
188 #define USB_DT_ENDPOINT_SIZE            7
189 #define USB_DT_ENDPOINT_AUDIO_SIZE      9       /* Audio extension */
190
191 /* most of these maximums are arbitrary */
192 #define USB_MAXCONFIG           8
193 #define USB_ALTSETTINGALLOC     4
194 #define USB_MAXALTSETTING       128  /* Hard limit */
195 #define USB_MAXINTERFACES       32
196 #define USB_MAXENDPOINTS        32   /* Hard limit */
197
198 /* All standard descriptors have these 2 fields in common */
199 struct usb_descriptor_header {
200         __u8  bLength;
201         __u8  bDescriptorType;
202 } __attribute__ ((packed));
203
204 /* USB_DT_DEVICE: Device descriptor */
205 struct usb_device_descriptor {
206         __u8  bLength;
207         __u8  bDescriptorType;
208         __u16 bcdUSB;
209         __u8  bDeviceClass;
210         __u8  bDeviceSubClass;
211         __u8  bDeviceProtocol;
212         __u8  bMaxPacketSize0;
213         __u16 idVendor;
214         __u16 idProduct;
215         __u16 bcdDevice;
216         __u8  iManufacturer;
217         __u8  iProduct;
218         __u8  iSerialNumber;
219         __u8  bNumConfigurations;
220 } __attribute__ ((packed));
221
222 /* USB_DT_ENDPOINT: Endpoint descriptor */
223 struct usb_endpoint_descriptor {
224         __u8  bLength           __attribute__ ((packed));
225         __u8  bDescriptorType   __attribute__ ((packed));
226         __u8  bEndpointAddress  __attribute__ ((packed));
227         __u8  bmAttributes      __attribute__ ((packed));
228         __u16 wMaxPacketSize    __attribute__ ((packed));
229         __u8  bInterval         __attribute__ ((packed));
230         __u8  bRefresh          __attribute__ ((packed));
231         __u8  bSynchAddress     __attribute__ ((packed));
232
233         /* the rest is internal to the Linux implementation */
234         unsigned char *extra;   /* Extra descriptors */
235         int extralen;
236 };
237
238 /* USB_DT_INTERFACE: Interface descriptor */
239 struct usb_interface_descriptor {
240         __u8  bLength           __attribute__ ((packed));
241         __u8  bDescriptorType   __attribute__ ((packed));
242         __u8  bInterfaceNumber  __attribute__ ((packed));
243         __u8  bAlternateSetting __attribute__ ((packed));
244         __u8  bNumEndpoints     __attribute__ ((packed));
245         __u8  bInterfaceClass   __attribute__ ((packed));
246         __u8  bInterfaceSubClass __attribute__ ((packed));
247         __u8  bInterfaceProtocol __attribute__ ((packed));
248         __u8  iInterface        __attribute__ ((packed));
249
250         /* the rest is internal to the Linux implementation */
251         struct usb_endpoint_descriptor *endpoint;
252
253         unsigned char *extra;   /* Extra descriptors */
254         int extralen;
255 };
256
257 struct usb_interface {
258         struct usb_interface_descriptor *altsetting;
259
260         int act_altsetting;             /* active alternate setting */
261         int num_altsetting;             /* number of alternate settings */
262         int max_altsetting;             /* total memory allocated */
263  
264         struct usb_driver *driver;      /* driver */
265         struct device dev;              /* interface specific device info */
266         void *private_data;
267 };
268
269 /* USB_DT_CONFIG: Configuration descriptor information.
270  *
271  * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
272  * descriptor type is different.  Highspeed-capable devices can look
273  * different depending on what speed they're currently running.  Only
274  * devices with a USB_DT_DEVICE_QUALIFIER have an OTHER_SPEED_CONFIG.
275  */
276 struct usb_config_descriptor {
277         __u8  bLength           __attribute__ ((packed));
278         __u8  bDescriptorType   __attribute__ ((packed));
279         __u16 wTotalLength      __attribute__ ((packed));
280         __u8  bNumInterfaces    __attribute__ ((packed));
281         __u8  bConfigurationValue __attribute__ ((packed));
282         __u8  iConfiguration    __attribute__ ((packed));
283         __u8  bmAttributes      __attribute__ ((packed));
284         __u8  MaxPower          __attribute__ ((packed));
285
286         /* the rest is internal to the Linux implementation */
287         struct usb_interface *interface;
288
289         unsigned char *extra;   /* Extra descriptors */
290         int extralen;
291 };
292
293 /* USB_DT_STRING: String descriptor */
294 struct usb_string_descriptor {
295         __u8  bLength;
296         __u8  bDescriptorType;
297         __u16 wData[1];         /* UTF-16LE encoded */
298 } __attribute__ ((packed));
299
300 /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
301 struct usb_qualifier_descriptor {
302         __u8  bLength;
303         __u8  bDescriptorType;
304         __u16 bcdUSB;
305         __u8  bDeviceClass;
306         __u8  bDeviceSubClass;
307         __u8  bDeviceProtocol;
308         __u8  bMaxPacketSize0;
309         __u8  bNumConfigurations;
310         __u8  bRESERVED;
311 } __attribute__ ((packed));
312
313 /* helpers for driver access to descriptors */
314 extern struct usb_interface *
315         usb_ifnum_to_if(struct usb_device *dev, unsigned ifnum);
316 extern struct usb_endpoint_descriptor *
317         usb_epnum_to_ep_desc(struct usb_device *dev, unsigned epnum);
318
319 int __usb_get_extra_descriptor(char *buffer, unsigned size,
320         unsigned char type, void **ptr);
321 #define usb_get_extra_descriptor(ifpoint,type,ptr)\
322         __usb_get_extra_descriptor((ifpoint)->extra,(ifpoint)->extralen,\
323                 type,(void**)ptr)
324
325 /*-------------------------------------------------------------------------*/
326
327 /*
328  * Device table entry for "new style" table-driven USB drivers.
329  * User mode code can read these tables to choose which modules to load.
330  * Declare the table as a MODULE_DEVICE_TABLE.
331  *
332  * The third probe() parameter will point to a matching entry from this
333  * table.  (Null value reserved.)  Use the driver_data field for each
334  * match to hold information tied to that match:  device quirks, etc.
335  * 
336  * Terminate the driver's table with an all-zeroes entry.
337  * Use the flag values to control which fields are compared.
338  */
339
340 /**
341  * struct usb_device_id - identifies USB devices for probing and hotplugging
342  * @match_flags: Bit mask controlling of the other fields are used to match
343  *      against new devices.  Any field except for driver_info may be used,
344  *      although some only make sense in conjunction with other fields.
345  *      This is usually set by a USB_DEVICE_*() macro, which sets all
346  *      other fields in this structure except for driver_info.
347  * @idVendor: USB vendor ID for a device; numbers are assigned
348  *      by the USB forum to its members.
349  * @idProduct: Vendor-assigned product ID.
350  * @bcdDevice_lo: Low end of range of vendor-assigned product version numbers.
351  *      This is also used to identify individual product versions, for
352  *      a range consisting of a single device.
353  * @bcdDevice_hi: High end of version number range.  The range of product
354  *      versions is inclusive.
355  * @bDeviceClass: Class of device; numbers are assigned
356  *      by the USB forum.  Products may choose to implement classes,
357  *      or be vendor-specific.  Device classes specify behavior of all
358  *      the interfaces on a devices.
359  * @bDeviceSubClass: Subclass of device; associated with bDeviceClass.
360  * @bDeviceProtocol: Protocol of device; associated with bDeviceClass.
361  * @bInterfaceClass: Class of interface; numbers are assigned
362  *      by the USB forum.  Products may choose to implement classes,
363  *      or be vendor-specific.  Interface classes specify behavior only
364  *      of a given interface; other interfaces may support other classes.
365  * @bInterfaceSubClass: Subclass of interface; associated with bInterfaceClass.
366  * @bInterfaceProtocol: Protocol of interface; associated with bInterfaceClass.
367  * @driver_info: Holds information used by the driver.  Usually it holds
368  *      a pointer to a descriptor understood by the driver, or perhaps
369  *      device flags.
370  *
371  * In most cases, drivers will create a table of device IDs by using
372  * USB_DEVICE(), or similar macros designed for that purpose.
373  * They will then export it to userspace using MODULE_DEVICE_TABLE(),
374  * and provide it to the USB core through their usb_driver structure.
375  *
376  * See the usb_match_id() function for information about how matches are
377  * performed.  Briefly, you will normally use one of several macros to help
378  * construct these entries.  Each entry you provide will either identify
379  * one or more specific products, or will identify a class of products
380  * which have agreed to behave the same.  You should put the more specific
381  * matches towards the beginning of your table, so that driver_info can
382  * record quirks of specific products.
383  */
384 struct usb_device_id {
385         /* which fields to match against? */
386         __u16           match_flags;
387
388         /* Used for product specific matches; range is inclusive */
389         __u16           idVendor;
390         __u16           idProduct;
391         __u16           bcdDevice_lo;
392         __u16           bcdDevice_hi;
393
394         /* Used for device class matches */
395         __u8            bDeviceClass;
396         __u8            bDeviceSubClass;
397         __u8            bDeviceProtocol;
398
399         /* Used for interface class matches */
400         __u8            bInterfaceClass;
401         __u8            bInterfaceSubClass;
402         __u8            bInterfaceProtocol;
403
404         /* not matched against */
405         unsigned long   driver_info;
406 };
407
408 /* Some useful macros to use to create struct usb_device_id */
409 #define USB_DEVICE_ID_MATCH_VENDOR              0x0001
410 #define USB_DEVICE_ID_MATCH_PRODUCT             0x0002
411 #define USB_DEVICE_ID_MATCH_DEV_LO              0x0004
412 #define USB_DEVICE_ID_MATCH_DEV_HI              0x0008
413 #define USB_DEVICE_ID_MATCH_DEV_CLASS           0x0010
414 #define USB_DEVICE_ID_MATCH_DEV_SUBCLASS        0x0020
415 #define USB_DEVICE_ID_MATCH_DEV_PROTOCOL        0x0040
416 #define USB_DEVICE_ID_MATCH_INT_CLASS           0x0080
417 #define USB_DEVICE_ID_MATCH_INT_SUBCLASS        0x0100
418 #define USB_DEVICE_ID_MATCH_INT_PROTOCOL        0x0200
419
420 #define USB_DEVICE_ID_MATCH_DEVICE              (USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
421 #define USB_DEVICE_ID_MATCH_DEV_RANGE           (USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
422 #define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION  (USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
423 #define USB_DEVICE_ID_MATCH_DEV_INFO \
424         (USB_DEVICE_ID_MATCH_DEV_CLASS | USB_DEVICE_ID_MATCH_DEV_SUBCLASS | USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
425 #define USB_DEVICE_ID_MATCH_INT_INFO \
426         (USB_DEVICE_ID_MATCH_INT_CLASS | USB_DEVICE_ID_MATCH_INT_SUBCLASS | USB_DEVICE_ID_MATCH_INT_PROTOCOL)
427
428 /**
429  * USB_DEVICE - macro used to describe a specific usb device
430  * @vend: the 16 bit USB Vendor ID
431  * @prod: the 16 bit USB Product ID
432  *
433  * This macro is used to create a struct usb_device_id that matches a
434  * specific device.
435  */
436 #define USB_DEVICE(vend,prod) \
437         match_flags: USB_DEVICE_ID_MATCH_DEVICE, idVendor: (vend), idProduct: (prod)
438 /**
439  * USB_DEVICE_VER - macro used to describe a specific usb device with a version range
440  * @vend: the 16 bit USB Vendor ID
441  * @prod: the 16 bit USB Product ID
442  * @lo: the bcdDevice_lo value
443  * @hi: the bcdDevice_hi value
444  *
445  * This macro is used to create a struct usb_device_id that matches a
446  * specific device, with a version range.
447  */
448 #define USB_DEVICE_VER(vend,prod,lo,hi) \
449         match_flags: USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, idVendor: (vend), idProduct: (prod), bcdDevice_lo: (lo), bcdDevice_hi: (hi)
450
451 /**
452  * USB_DEVICE_INFO - macro used to describe a class of usb devices
453  * @cl: bDeviceClass value
454  * @sc: bDeviceSubClass value
455  * @pr: bDeviceProtocol value
456  *
457  * This macro is used to create a struct usb_device_id that matches a
458  * specific class of devices.
459  */
460 #define USB_DEVICE_INFO(cl,sc,pr) \
461         match_flags: USB_DEVICE_ID_MATCH_DEV_INFO, bDeviceClass: (cl), bDeviceSubClass: (sc), bDeviceProtocol: (pr)
462
463 /**
464  * USB_INTERFACE_INFO - macro used to describe a class of usb interfaces 
465  * @cl: bInterfaceClass value
466  * @sc: bInterfaceSubClass value
467  * @pr: bInterfaceProtocol value
468  *
469  * This macro is used to create a struct usb_device_id that matches a
470  * specific class of interfaces.
471  */
472 #define USB_INTERFACE_INFO(cl,sc,pr) \
473         match_flags: USB_DEVICE_ID_MATCH_INT_INFO, bInterfaceClass: (cl), bInterfaceSubClass: (sc), bInterfaceProtocol: (pr)
474
475 /* -------------------------------------------------------------------------- */
476
477 /**
478  * struct usb_driver - identifies USB driver to usbcore
479  * @owner: pointer to the module owner of this driver
480  * @name: The driver name should be unique among USB drivers
481  * @probe: Called to see if the driver is willing to manage a particular
482  *      interface on a device.  The probe routine returns a handle that 
483  *      will later be provided to disconnect(), or a null pointer to
484  *      indicate that the driver will not handle the interface.
485  *      The handle is normally a pointer to driver-specific data.
486  *      If the probe() routine needs to access the interface
487  *      structure itself, use usb_ifnum_to_if() to make sure it's using
488  *      the right one.
489  * @disconnect: Called when the interface is no longer accessible, usually
490  *      because its device has been (or is being) disconnected.  The
491  *      handle passed is what was returned by probe(), or was provided
492  *      to usb_driver_claim_interface().
493  * @fops: USB drivers can reuse some character device framework in
494  *      the USB subsystem by providing a file operations vector and
495  *      a minor number.
496  * @minor: Used with fops to simplify creating USB character devices.
497  *      Such drivers have sixteen character devices, using the USB
498  *      major number and starting with this minor number.
499  * @ioctl: Used for drivers that want to talk to userspace through
500  *      the "usbfs" filesystem.  This lets devices provide ways to
501  *      expose information to user space regardless of where they
502  *      do (or don't) show up otherwise in the filesystem.
503  * @id_table: USB drivers use ID table to support hotplugging.
504  *      Export this with MODULE_DEVICE_TABLE(usb,...), or use NULL to
505  *      say that probe() should be called for any unclaimed interfce.
506  *
507  * USB drivers should provide a name, probe() and disconnect() methods,
508  * and an id_table.  Other driver fields are optional.
509  *
510  * The id_table is used in hotplugging.  It holds a set of descriptors,
511  * and specialized data may be associated with each entry.  That table
512  * is used by both user and kernel mode hotplugging support.
513  *
514  * The probe() and disconnect() methods are called in a context where
515  * they can sleep, but they should avoid abusing the privilage.  Most
516  * work to connect to a device should be done when the device is opened,
517  * and undone at the last close.  The disconnect code needs to address
518  * concurrency issues with respect to open() and close() methods, as
519  * well as cancel any I/O requests that are still pending.
520  */
521 struct usb_driver {
522         struct module *owner;
523         const char *name;
524
525         void *(*probe)(
526             struct usb_device *dev,             /* the device */
527             unsigned intf,                      /* what interface */
528             const struct usb_device_id *id      /* from id_table */
529             );
530         void (*disconnect)(
531             struct usb_device *dev,             /* the device */
532             void *handle                        /* as returned by probe() */
533             );
534
535         struct list_head driver_list;
536
537         struct file_operations *fops;
538         int minor;
539
540         struct semaphore serialize;
541
542         /* ioctl -- userspace apps can talk to drivers through usbfs */
543         int (*ioctl)(struct usb_device *dev, unsigned int code, void *buf);
544
545         /* support for "new-style" USB hotplugging */
546         const struct usb_device_id *id_table;
547
548         /* suspend before the bus suspends;
549          * disconnect or resume when the bus resumes */
550         /* void (*suspend)(struct usb_device *dev); */
551         /* void (*resume)(struct usb_device *dev); */
552 };
553
554 /*
555  * use these in module_init()/module_exit()
556  * and don't forget MODULE_DEVICE_TABLE(usb, ...)
557  */
558 extern int usb_register(struct usb_driver *);
559 extern void usb_deregister(struct usb_driver *);
560
561 /* -------------------------------------------------------------------------- */
562
563 /*
564  * URB support, for asynchronous request completions
565  */
566
567 /*
568  * urb->transfer_flags:
569  *
570  * FIXME should be URB_* flags
571  */
572 #define USB_DISABLE_SPD         0x0001
573 #define USB_ISO_ASAP            0x0002
574 #define USB_ASYNC_UNLINK        0x0008
575 #define USB_QUEUE_BULK          0x0010
576 #define USB_NO_FSBR             0x0020
577 #define USB_ZERO_PACKET         0x0040  /* Finish bulk OUTs with short packet */
578 #define URB_NO_INTERRUPT        0x0080  /* HINT: no non-error interrupt needed */
579                                         /* ... less overhead for QUEUE_BULK */
580 #define USB_TIMEOUT_KILLED      0x1000  /* only set by HCD! */
581
582 struct usb_iso_packet_descriptor {
583         unsigned int offset;
584         unsigned int length;            /* expected length */
585         unsigned int actual_length;
586         unsigned int status;
587 };
588
589 struct urb;
590
591 typedef void (*usb_complete_t)(struct urb *);
592
593 /**
594  * struct urb - USB Request Block
595  * @urb_list: For use by current owner of the URB.
596  * @next: Used primarily to link ISO requests into rings.
597  * @pipe: Holds endpoint number, direction, type, and max packet size.
598  *      Create these values with the eight macros available;
599  *      usb_{snd,rcv}TYPEpipe(dev,endpoint), where the type is "ctrl"
600  *      (control), "bulk", "int" (interrupt), or "iso" (isochronous).
601  *      For example usb_sndbulkpipe() or usb_rcvintpipe().  Endpoint
602  *      numbers range from zero to fifteen.  Note that "in" endpoint two
603  *      is a different endpoint (and pipe) from "out" endpoint two.
604  *      The current configuration controls the existence, type, and
605  *      maximum packet size of any given endpoint.
606  * @dev: Identifies the USB device to perform the request.
607  * @status: This is read in non-iso completion functions to get the
608  *      status of the particular request.  ISO requests only use it
609  *      to tell whether the URB was unlinked; detailed status for
610  *      each frame is in the fields of the iso_frame-desc.
611  * @transfer_flags: A variety of flags may be used to affect how URB
612  *      submission, unlinking, or operation are handled.  Different
613  *      kinds of URB can use different flags.
614  * @transfer_buffer: For non-iso transfers, this identifies the buffer
615  *      to (or from) which the I/O request will be performed.  This
616  *      buffer must be suitable for DMA; allocate it with kmalloc()
617  *      or equivalent.  For transfers to "in" endpoints, contents of
618  *      this buffer will be modified.
619  * @transfer_buffer_length: How big is transfer_buffer.  The transfer may
620  *      be broken up into chunks according to the current maximum packet
621  *      size for the endpoint, which is a function of the configuration
622  *      and is encoded in the pipe.
623  * @actual_length: This is read in non-iso completion functions, and
624  *      it tells how many bytes (out of transfer_buffer_length) were
625  *      transferred.  It will normally be the same as requested, unless
626  *      either an error was reported or a short read was performed and
627  *      the USB_DISABLE_SPD transfer flag was used to say that such
628  *      short reads are not errors. 
629  * @setup_packet: Only used for control transfers, this points to eight bytes
630  *      of setup data.  Control transfers always start by sending this data
631  *      to the device.  Then transfer_buffer is read or written, if needed.
632  * @start_frame: Returns the initial frame for interrupt or isochronous
633  *      transfers.
634  * @number_of_packets: Lists the number of ISO transfer buffers.
635  * @interval: Specifies the polling interval for interrupt transfers, in
636  *      milliseconds.
637  * @error_count: Returns the number of ISO transfers that reported errors.
638  * @context: For use in completion functions.  This normally points to
639  *      request-specific driver context.
640  * @complete: Completion handler. This URB is passed as the parameter to the
641  *      completion function.  Except for interrupt or isochronous transfers
642  *      that aren't being unlinked, the completion function may then do what
643  *      it likes with the URB, including resubmitting or freeing it.
644  * @iso_frame_desc: Used to provide arrays of ISO transfer buffers and to 
645  *      collect the transfer status for each buffer.
646  *
647  * This structure identifies USB transfer requests.  URBs must be allocated by
648  * calling usb_alloc_urb() and freed with a call to usb_free_urb().
649  * Initialization may be done using various usb_fill_*_urb() functions.  URBs
650  * are submitted using usb_submit_urb(), and pending requests may be canceled
651  * using usb_unlink_urb().
652  *
653  * Initialization:
654  *
655  * All URBs submitted must initialize dev, pipe, next (may be null),
656  * transfer_flags (may be zero), complete, timeout (may be zero).
657  * The USB_ASYNC_UNLINK transfer flag affects later invocations of
658  * the usb_unlink_urb() routine.
659  *
660  * All non-isochronous URBs must also initialize 
661  * transfer_buffer and transfer_buffer_length.  They may provide the
662  * USB_DISABLE_SPD transfer flag, indicating that short reads are
663  * not to be treated as errors.
664  *
665  * Bulk URBs may pass the USB_QUEUE_BULK transfer flag, telling the host
666  * controller driver never to report an error if several bulk requests get
667  * queued to the same endpoint.  Such queueing supports more efficient use
668  * of bus bandwidth, minimizing delays due to interrupts and scheduling,
669  * if the host controller hardware is smart enough.  Bulk URBs can also
670  * use the USB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
671  * should always terminate with a short packet, even if it means adding an
672  * extra zero length packet.
673  *
674  * Control URBs must provide a setup_packet.
675  *
676  * Interupt UBS must provide an interval, saying how often (in milliseconds)
677  * to poll for transfers.  After the URB has been submitted, the interval
678  * and start_frame fields reflect how the transfer was actually scheduled.
679  * The polling interval may be more frequent than requested.
680  * For example, some controllers have a maximum interval of 32 microseconds,
681  * while others support intervals of up to 1024 microseconds.
682  *
683  * Isochronous URBs normally use the USB_ISO_ASAP transfer flag, telling
684  * the host controller to schedule the transfer as soon as bandwidth
685  * utilization allows, and then set start_frame to reflect the actual frame
686  * selected during submission.  Otherwise drivers must specify the start_frame
687  * and handle the case where the transfer can't begin then.  However, drivers
688  * won't know how bandwidth is currently allocated, and while they can
689  * find the current frame using usb_get_current_frame_number () they can't
690  * know the range for that frame number.  (Common ranges for the frame
691  * counter include 256, 512, and 1024 frames.)
692  *
693  * Isochronous URBs have a different data transfer model, in part because
694  * the quality of service is only "best effort".  Callers provide specially
695  * allocated URBs, with number_of_packets worth of iso_frame_desc structures
696  * at the end.  Each such packet is an individual ISO transfer.  Isochronous
697  * URBs are normally submitted with urb->next fields set up as a ring, so
698  * that data (such as audio or video) streams at as constant a rate as the
699  * host controller scheduler can support.
700  *
701  * Completion Callbacks:
702  *
703  * The completion callback is made in_interrupt(), and one of the first
704  * things that a completion handler should do is check the status field.
705  * The status field is provided for all URBs.  It is used to report
706  * unlinked URBs, and status for all non-ISO transfers.  It should not
707  * be examined outside of the completion handler.
708  *
709  * The context field is normally used to link URBs back to the relevant
710  * driver or request state.
711  *
712  * When completion callback is invoked for non-isochronous URBs, the
713  * actual_length field tells how many bytes were transferred.
714  *
715  * For interrupt and isochronous URBs, the URB provided to the callback
716  * function is still "owned" by the USB core subsystem unless the status
717  * indicates that the URB has been unlinked.  Completion handlers should
718  * not modify such URBs until they have been unlinked.
719  *
720  * ISO transfer status is reported in the status and actual_length fields
721  * of the iso_frame_desc array, and the number of errors is reported in
722  * error_count.
723  */
724 struct urb
725 {
726         spinlock_t lock;                /* lock for the URB */
727         atomic_t count;                 /* reference count of the URB */
728         void *hcpriv;                   /* private data for host controller */
729         struct list_head urb_list;      /* list pointer to all active urbs */
730         struct urb *next;               /* (in) pointer to next URB */
731         struct usb_device *dev;         /* (in) pointer to associated device */
732         unsigned int pipe;              /* (in) pipe information */
733         int status;                     /* (return) non-ISO status */
734         unsigned int transfer_flags;    /* (in) USB_DISABLE_SPD | ...*/
735         void *transfer_buffer;          /* (in) associated data buffer */
736         int transfer_buffer_length;     /* (in) data buffer length */
737         int actual_length;              /* (return) actual transfer length */
738         int bandwidth;                  /* bandwidth for INT/ISO request */
739         unsigned char *setup_packet;    /* (in) setup packet (control only) */
740         int start_frame;                /* (modify) start frame (INT/ISO) */
741         int number_of_packets;          /* (in) number of ISO packets */
742         int interval;                   /* (in) polling interval (INT only) */
743         int error_count;                /* (return) number of ISO errors */
744         int timeout;                    /* (in) timeout, in jiffies */
745         void *context;                  /* (in) context for completion */
746         usb_complete_t complete;        /* (in) completion routine */
747         struct usb_iso_packet_descriptor iso_frame_desc[0];     /* (in) ISO ONLY */
748 };
749
750 /**
751  * usb_fill_control_urb - initializes a control urb
752  * @urb: pointer to the urb to initialize.
753  * @dev: pointer to the struct usb_device for this urb.
754  * @pipe: the endpoint pipe
755  * @setup_packet: pointer to the setup_packet buffer
756  * @transfer_buffer: pointer to the transfer buffer
757  * @buffer_length: length of the transfer buffer
758  * @complete: pointer to the usb_complete_t function
759  * @context: what to set the urb context to.
760  *
761  * Initializes a control urb with the proper information needed to submit
762  * it to a device.
763  */
764 static inline void usb_fill_control_urb (struct urb *urb,
765                                          struct usb_device *dev,
766                                          unsigned int pipe,
767                                          unsigned char *setup_packet,
768                                          void *transfer_buffer,
769                                          int buffer_length,
770                                          usb_complete_t complete,
771                                          void *context)
772 {
773         spin_lock_init(&urb->lock);
774         urb->dev = dev;
775         urb->pipe = pipe;
776         urb->setup_packet = setup_packet;
777         urb->transfer_buffer = transfer_buffer;
778         urb->transfer_buffer_length = buffer_length;
779         urb->complete = complete;
780         urb->context = context;
781 }
782
783 /**
784  * usb_fill_bulk_urb - macro to help initialize a bulk urb
785  * @urb: pointer to the urb to initialize.
786  * @dev: pointer to the struct usb_device for this urb.
787  * @pipe: the endpoint pipe
788  * @transfer_buffer: pointer to the transfer buffer
789  * @buffer_length: length of the transfer buffer
790  * @complete: pointer to the usb_complete_t function
791  * @context: what to set the urb context to.
792  *
793  * Initializes a bulk urb with the proper information needed to submit it
794  * to a device.
795  */
796 static inline void usb_fill_bulk_urb (struct urb *urb,
797                                       struct usb_device *dev,
798                                       unsigned int pipe,
799                                       void *transfer_buffer,
800                                       int buffer_length,
801                                       usb_complete_t complete,
802                                       void *context)
803                                       
804 {
805         spin_lock_init(&urb->lock);
806         urb->dev = dev;
807         urb->pipe = pipe;
808         urb->transfer_buffer = transfer_buffer;
809         urb->transfer_buffer_length = buffer_length;
810         urb->complete = complete;
811         urb->context = context;
812 }
813     
814 /**
815  * usb_fill_int_urb - macro to help initialize a interrupt urb
816  * @urb: pointer to the urb to initialize.
817  * @dev: pointer to the struct usb_device for this urb.
818  * @pipe: the endpoint pipe
819  * @transfer_buffer: pointer to the transfer buffer
820  * @buffer_length: length of the transfer buffer
821  * @complete: pointer to the usb_complete_t function
822  * @context: what to set the urb context to.
823  * @interval: what to set the urb interval to.
824  *
825  * Initializes a interrupt urb with the proper information needed to submit
826  * it to a device.
827  */
828 static inline void usb_fill_int_urb (struct urb *urb,
829                                      struct usb_device *dev,
830                                      unsigned int pipe,
831                                      void *transfer_buffer,
832                                      int buffer_length,
833                                      usb_complete_t complete,
834                                      void *context,
835                                      int interval)
836 {
837         spin_lock_init(&urb->lock);
838         urb->dev = dev;
839         urb->pipe = pipe;
840         urb->transfer_buffer = transfer_buffer;
841         urb->transfer_buffer_length = buffer_length;
842         urb->complete = complete;
843         urb->context = context;
844         urb->interval = interval;
845         urb->start_frame = -1;
846 }
847
848 /*
849  * old style macros to enable 2.4 and 2.2 drivers to build
850  * properly.  Please do not use these for new USB drivers.
851  */
852 #define FILL_CONTROL_URB(URB,DEV,PIPE,SETUP_PACKET,TRANSFER_BUFFER,BUFFER_LENGTH,COMPLETE,CONTEXT) \
853     usb_fill_control_urb(URB,DEV,PIPE,SETUP_PACKET,TRANSFER_BUFFER,BUFFER_LENGTH,COMPLETE,CONTEXT)
854 #define FILL_BULK_URB(URB,DEV,PIPE,TRANSFER_BUFFER,BUFFER_LENGTH,COMPLETE,CONTEXT) \
855     usb_fill_bulk_urb(URB,DEV,PIPE,TRANSFER_BUFFER,BUFFER_LENGTH,COMPLETE,CONTEXT)
856 #define FILL_INT_URB(URB,DEV,PIPE,TRANSFER_BUFFER,BUFFER_LENGTH,COMPLETE,CONTEXT,INTERVAL) \
857     usb_fill_int_urb(URB,DEV,PIPE,TRANSFER_BUFFER,BUFFER_LENGTH,COMPLETE,CONTEXT,INTERVAL)
858
859 extern struct urb *usb_alloc_urb(int iso_packets);
860 extern void usb_free_urb(struct urb *urb);
861 #define usb_put_urb usb_free_urb
862 extern struct urb *usb_get_urb(struct urb *urb);
863 extern int usb_submit_urb(struct urb *urb, int mem_flags);
864 extern int usb_unlink_urb(struct urb *urb);
865
866 /*-------------------------------------------------------------------*
867  *                         SYNCHRONOUS CALL SUPPORT                  *
868  *-------------------------------------------------------------------*/
869
870 extern int usb_control_msg(struct usb_device *dev, unsigned int pipe,
871         __u8 request, __u8 requesttype, __u16 value, __u16 index,
872         void *data, __u16 size, int timeout);
873 extern int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
874         void *data, int len, int *actual_length,
875         int timeout);
876
877 /* wrappers around usb_control_msg() for the most common standard requests */
878 extern int usb_clear_halt(struct usb_device *dev, int pipe);
879 extern int usb_get_descriptor(struct usb_device *dev, unsigned char desctype,
880         unsigned char descindex, void *buf, int size);
881 extern int usb_get_device_descriptor(struct usb_device *dev);
882 extern int usb_get_status(struct usb_device *dev,
883         int type, int target, void *data);
884 extern int usb_get_string(struct usb_device *dev,
885         unsigned short langid, unsigned char index, void *buf, int size);
886 extern int usb_string(struct usb_device *dev, int index,
887         char *buf, size_t size);
888 extern int usb_set_configuration(struct usb_device *dev, int configuration);
889 extern int usb_set_interface(struct usb_device *dev, int ifnum, int alternate);
890 extern int usb_make_path(struct usb_device *dev, char *buf, size_t size);
891
892 /*
893  * timeouts, in seconds, used for sending/receiving control messages
894  * they typically complete within a few frames (msec) after they're issued
895  */
896 #ifdef CONFIG_USB_LONG_TIMEOUT
897 #define USB_CTRL_GET_TIMEOUT 4
898 #else
899 #define USB_CTRL_GET_TIMEOUT 3
900 #endif
901
902 #define USB_CTRL_SET_TIMEOUT 3
903
904 /* -------------------------------------------------------------------------- */
905
906 /* Host Controller Driver (HCD) support */
907
908 struct usb_operations {
909         int (*allocate)(struct usb_device *);
910         int (*deallocate)(struct usb_device *);
911         int (*get_frame_number) (struct usb_device *usb_dev);
912         int (*submit_urb) (struct urb *urb, int mem_flags);
913         int (*unlink_urb) (struct urb *urb);
914 };
915
916 #define DEVNUM_ROUND_ROBIN      /***** OPTION *****/
917
918 /*
919  * Allocated per bus we have
920  */
921 struct usb_bus {
922         int busnum;                     /* Bus number (in order of reg) */
923
924 #ifdef DEVNUM_ROUND_ROBIN
925         int devnum_next;                /* Next open device number in round-robin allocation */
926 #endif /* DEVNUM_ROUND_ROBIN */
927
928         struct usb_devmap devmap;       /* Device map */
929         struct usb_operations *op;      /* Operations (specific to the HC) */
930         struct usb_device *root_hub;    /* Root hub */
931         struct list_head bus_list;
932         void *hcpriv;                   /* Host Controller private data */
933
934         int bandwidth_allocated;        /* on this Host Controller; */
935                                           /* applies to Int. and Isoc. pipes; */
936                                           /* measured in microseconds/frame; */
937                                           /* range is 0..900, where 900 = */
938                                           /* 90% of a 1-millisecond frame */
939         int bandwidth_int_reqs;         /* number of Interrupt requesters */
940         int bandwidth_isoc_reqs;        /* number of Isoc. requesters */
941
942         struct dentry *dentry;          /* usbfs dentry entry for the bus */
943
944         atomic_t refcnt;
945 };
946
947 extern struct usb_bus *usb_alloc_bus(struct usb_operations *);
948 extern void usb_free_bus(struct usb_bus *);
949 extern void usb_register_bus(struct usb_bus *);
950 extern void usb_deregister_bus(struct usb_bus *);
951 extern int usb_register_root_hub(struct usb_device *usb_dev, struct device *parent_dev);
952
953 extern int usb_check_bandwidth (struct usb_device *dev, struct urb *urb);
954 extern void usb_claim_bandwidth (struct usb_device *dev, struct urb *urb,
955                 int bustime, int isoc);
956 extern void usb_release_bandwidth(struct usb_device *dev, struct urb *urb,
957                 int isoc);
958 extern int usb_root_hub_string(int id, int serial,
959                 char *type, __u8 *data, int len);
960
961 /*
962  * Some USB 1.1 bandwidth allocation constants.
963  */
964 #define BW_HOST_DELAY   1000L           /* nanoseconds */
965 #define BW_HUB_LS_SETUP 333L            /* nanoseconds */
966                         /* 4 full-speed bit times (est.) */
967
968 #define FRAME_TIME_BITS         12000L          /* frame = 1 millisecond */
969 #define FRAME_TIME_MAX_BITS_ALLOC       (90L * FRAME_TIME_BITS / 100L)
970 #define FRAME_TIME_USECS        1000L
971 #define FRAME_TIME_MAX_USECS_ALLOC      (90L * FRAME_TIME_USECS / 100L)
972
973 #define BitTime(bytecount)  (7 * 8 * bytecount / 6)  /* with integer truncation */
974                 /* Trying not to use worst-case bit-stuffing
975                    of (7/6 * 8 * bytecount) = 9.33 * bytecount */
976                 /* bytecount = data payload byte count */
977
978 #define NS_TO_US(ns)    ((ns + 500L) / 1000L)
979                         /* convert & round nanoseconds to microseconds */
980
981 /*
982  * As of USB 2.0, full/low speed devices are segregated into trees.
983  * One type grows from USB 1.1 host controllers (OHCI, UHCI etc).
984  * The other type grows from high speed hubs when they connect to
985  * full/low speed devices using "Transaction Translators" (TTs).
986  *
987  * TTs should only be known to the hub driver, and high speed bus
988  * drivers (only EHCI for now).  They affect periodic scheduling and
989  * sometimes control/bulk error recovery.
990  */
991 struct usb_tt {
992         struct usb_device       *hub;   /* upstream highspeed hub */
993         int                     multi;  /* true means one TT per port */
994 };
995
996
997 /* -------------------------------------------------------------------------- */
998
999 /* Enumeration is only for the hub driver, or HCD virtual root hubs */
1000 extern struct usb_device *usb_alloc_dev(struct usb_device *parent,
1001         struct usb_bus *);
1002 extern void usb_free_dev(struct usb_device *);
1003 extern int usb_new_device(struct usb_device *dev);
1004 extern void usb_connect(struct usb_device *dev);
1005 extern void usb_disconnect(struct usb_device **);
1006
1007 #ifndef _LINUX_HUB_H
1008 /* exported to hub driver ONLY to support usb_reset_device () */
1009 extern int usb_get_configuration(struct usb_device *dev);
1010 extern void usb_set_maxpacket(struct usb_device *dev);
1011 extern void usb_destroy_configuration(struct usb_device *dev);
1012 extern int usb_set_address(struct usb_device *dev);
1013 #endif /* _LINUX_HUB_H */
1014
1015 /* -------------------------------------------------------------------------- */
1016
1017 /* This is arbitrary.
1018  * From USB 2.0 spec Table 11-13, offset 7, a hub can
1019  * have up to 255 ports. The most yet reported is 10.
1020  */
1021 #define USB_MAXCHILDREN         (16)
1022
1023 struct usb_device {
1024         int             devnum;         /* Address on USB bus */
1025         char            devpath [16];   /* Use in messages: /port/port/... */
1026
1027         enum {
1028                 USB_SPEED_UNKNOWN = 0,                  /* enumerating */
1029                 USB_SPEED_LOW, USB_SPEED_FULL,          /* usb 1.1 */
1030                 USB_SPEED_HIGH                          /* usb 2.0 */
1031         } speed;
1032
1033         struct usb_tt   *tt;            /* low/full speed dev, highspeed hub */
1034         int             ttport;         /* device port on that tt hub */
1035
1036         atomic_t refcnt;                /* Reference count */
1037         struct semaphore serialize;
1038
1039         unsigned int toggle[2];         /* one bit for each endpoint ([0] = IN, [1] = OUT) */
1040         unsigned int halted[2];         /* endpoint halts; one bit per endpoint # & direction; */
1041                                         /* [0] = IN, [1] = OUT */
1042         int epmaxpacketin[16];          /* INput endpoint specific maximums */
1043         int epmaxpacketout[16];         /* OUTput endpoint specific maximums */
1044
1045         struct usb_device *parent;
1046         struct usb_bus *bus;            /* Bus we're part of */
1047
1048         struct device dev;              /* Generic device interface */
1049
1050         struct usb_device_descriptor descriptor;/* Descriptor */
1051         struct usb_config_descriptor *config;   /* All of the configs */
1052         struct usb_config_descriptor *actconfig;/* the active configuration */
1053
1054         char **rawdescriptors;          /* Raw descriptors for each config */
1055
1056         int have_langid;                /* whether string_langid is valid yet */
1057         int string_langid;              /* language ID for strings */
1058   
1059         void *hcpriv;                   /* Host Controller private data */
1060         
1061         struct list_head filelist;
1062         struct dentry *dentry;          /* usbfs dentry entry for the device */
1063
1064         /*
1065          * Child devices - these can be either new devices
1066          * (if this is a hub device), or different instances
1067          * of this same device.
1068          *
1069          * Each instance needs its own set of data structures.
1070          */
1071
1072         int maxchild;                   /* Number of ports if hub */
1073         struct usb_device *children[USB_MAXCHILDREN];
1074 };
1075
1076 /* for when layers above USB add new non-USB drivers */
1077 extern void usb_scan_devices(void);
1078
1079 /* mostly for devices emulating SCSI over USB */
1080 extern int usb_reset_device(struct usb_device *dev);
1081
1082 /* for drivers using iso endpoints */
1083 extern int usb_get_current_frame_number (struct usb_device *usb_dev);
1084
1085 /* drivers must track when they bind to a device's interfaces */
1086 extern void usb_inc_dev_use(struct usb_device *);
1087 #define usb_dec_dev_use usb_free_dev
1088
1089 /* used these for multi-interface device registration */
1090 extern void usb_driver_claim_interface(struct usb_driver *driver,
1091                         struct usb_interface *iface, void* priv);
1092 extern int usb_interface_claimed(struct usb_interface *iface);
1093 extern void usb_driver_release_interface(struct usb_driver *driver,
1094                         struct usb_interface *iface);
1095 const struct usb_device_id *usb_match_id(struct usb_device *dev,
1096                                          struct usb_interface *interface,
1097                                          const struct usb_device_id *id);
1098
1099 /* -------------------------------------------------------------------------- */
1100
1101 /*
1102  * Calling this entity a "pipe" is glorifying it. A USB pipe
1103  * is something embarrassingly simple: it basically consists
1104  * of the following information:
1105  *  - device number (7 bits)
1106  *  - endpoint number (4 bits)
1107  *  - current Data0/1 state (1 bit) [Historical; now gone]
1108  *  - direction (1 bit)
1109  *  - speed (1 bit) [Historical and specific to USB 1.1; now gone.]
1110  *  - max packet size (2 bits: 8, 16, 32 or 64) [Historical; now gone.]
1111  *  - pipe type (2 bits: control, interrupt, bulk, isochronous)
1112  *
1113  * That's 18 bits. Really. Nothing more. And the USB people have
1114  * documented these eighteen bits as some kind of glorious
1115  * virtual data structure.
1116  *
1117  * Let's not fall in that trap. We'll just encode it as a simple
1118  * unsigned int. The encoding is:
1119  *
1120  *  - max size:         bits 0-1        [Historical; now gone.]
1121  *  - direction:        bit 7           (0 = Host-to-Device [Out],
1122  *                                       1 = Device-to-Host [In])
1123  *  - device:           bits 8-14
1124  *  - endpoint:         bits 15-18
1125  *  - Data0/1:          bit 19          [Historical; now gone. ]
1126  *  - lowspeed:         bit 26          [Historical; now gone. ]
1127  *  - pipe type:        bits 30-31      (00 = isochronous, 01 = interrupt,
1128  *                                       10 = control, 11 = bulk)
1129  *
1130  * Why? Because it's arbitrary, and whatever encoding we select is really
1131  * up to us. This one happens to share a lot of bit positions with the UHCI
1132  * specification, so that much of the uhci driver can just mask the bits
1133  * appropriately.
1134  */
1135
1136 #define PIPE_ISOCHRONOUS                0
1137 #define PIPE_INTERRUPT                  1
1138 #define PIPE_CONTROL                    2
1139 #define PIPE_BULK                       3
1140
1141 #define usb_maxpacket(dev, pipe, out)   (out \
1142                                 ? (dev)->epmaxpacketout[usb_pipeendpoint(pipe)] \
1143                                 : (dev)->epmaxpacketin [usb_pipeendpoint(pipe)] )
1144 #define usb_packetid(pipe)      (((pipe) & USB_DIR_IN) ? USB_PID_IN : USB_PID_OUT)
1145
1146 #define usb_pipeout(pipe)       ((((pipe) >> 7) & 1) ^ 1)
1147 #define usb_pipein(pipe)        (((pipe) >> 7) & 1)
1148 #define usb_pipedevice(pipe)    (((pipe) >> 8) & 0x7f)
1149 #define usb_pipeendpoint(pipe)  (((pipe) >> 15) & 0xf)
1150 #define usb_pipetype(pipe)      (((pipe) >> 30) & 3)
1151 #define usb_pipeisoc(pipe)      (usb_pipetype((pipe)) == PIPE_ISOCHRONOUS)
1152 #define usb_pipeint(pipe)       (usb_pipetype((pipe)) == PIPE_INTERRUPT)
1153 #define usb_pipecontrol(pipe)   (usb_pipetype((pipe)) == PIPE_CONTROL)
1154 #define usb_pipebulk(pipe)      (usb_pipetype((pipe)) == PIPE_BULK)
1155
1156 #define PIPE_DEVEP_MASK         0x0007ff00
1157
1158 /* The D0/D1 toggle bits */
1159 #define usb_gettoggle(dev, ep, out) (((dev)->toggle[out] >> (ep)) & 1)
1160 #define usb_dotoggle(dev, ep, out)  ((dev)->toggle[out] ^= (1 << (ep)))
1161 #define usb_settoggle(dev, ep, out, bit) ((dev)->toggle[out] = ((dev)->toggle[out] & ~(1 << (ep))) | ((bit) << (ep)))
1162
1163 /* Endpoint halt control/status */
1164 #define usb_endpoint_out(ep_dir)        ((((ep_dir) >> 7) & 1) ^ 1)
1165 #define usb_endpoint_halt(dev, ep, out) ((dev)->halted[out] |= (1 << (ep)))
1166 #define usb_endpoint_running(dev, ep, out) ((dev)->halted[out] &= ~(1 << (ep)))
1167 #define usb_endpoint_halted(dev, ep, out) ((dev)->halted[out] & (1 << (ep)))
1168
1169 static inline unsigned int __create_pipe(struct usb_device *dev, unsigned int endpoint)
1170 {
1171         return (dev->devnum << 8) | (endpoint << 15);
1172 }
1173
1174 /* Create various pipes... */
1175 #define usb_sndctrlpipe(dev,endpoint)   ((PIPE_CONTROL << 30) | __create_pipe(dev,endpoint))
1176 #define usb_rcvctrlpipe(dev,endpoint)   ((PIPE_CONTROL << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
1177 #define usb_sndisocpipe(dev,endpoint)   ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev,endpoint))
1178 #define usb_rcvisocpipe(dev,endpoint)   ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
1179 #define usb_sndbulkpipe(dev,endpoint)   ((PIPE_BULK << 30) | __create_pipe(dev,endpoint))
1180 #define usb_rcvbulkpipe(dev,endpoint)   ((PIPE_BULK << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
1181 #define usb_sndintpipe(dev,endpoint)    ((PIPE_INTERRUPT << 30) | __create_pipe(dev,endpoint))
1182 #define usb_rcvintpipe(dev,endpoint)    ((PIPE_INTERRUPT << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
1183 #define usb_snddefctrl(dev)             ((PIPE_CONTROL << 30))
1184 #define usb_rcvdefctrl(dev)             ((PIPE_CONTROL << 30) | USB_DIR_IN)
1185
1186 /* -------------------------------------------------------------------------- */
1187
1188 /*
1189  * Debugging and troubleshooting/diagnostic helpers.
1190  */
1191 void usb_show_device_descriptor(struct usb_device_descriptor *);
1192 void usb_show_config_descriptor(struct usb_config_descriptor *);
1193 void usb_show_interface_descriptor(struct usb_interface_descriptor *);
1194 void usb_show_endpoint_descriptor(struct usb_endpoint_descriptor *);
1195 void usb_show_device(struct usb_device *);
1196 void usb_show_string(struct usb_device *dev, char *id, int index);
1197
1198 #ifdef DEBUG
1199 #define dbg(format, arg...) printk(KERN_DEBUG __FILE__ ": " format "\n" , ## arg)
1200 #else
1201 #define dbg(format, arg...) do {} while (0)
1202 #endif
1203
1204 #define err(format, arg...) printk(KERN_ERR __FILE__ ": " format "\n" , ## arg)
1205 #define info(format, arg...) printk(KERN_INFO __FILE__ ": " format "\n" , ## arg)
1206 #define warn(format, arg...) printk(KERN_WARNING __FILE__ ": " format "\n" , ## arg)
1207
1208
1209 /* -------------------------------------------------------------------------- */
1210
1211 /*
1212  * bus and driver list
1213  * exported only for usbfs (not visible outside usbcore)
1214  */
1215
1216 extern struct list_head usb_driver_list;
1217 extern struct list_head usb_bus_list;
1218 extern struct semaphore usb_bus_list_lock;
1219
1220 /*
1221  * USB device fs stuff
1222  */
1223
1224 #ifdef CONFIG_USB_DEVICEFS
1225
1226 /*
1227  * these are expected to be called from the USB core/hub thread
1228  * with the kernel lock held
1229  */
1230 extern void usbfs_add_bus(struct usb_bus *bus);
1231 extern void usbfs_remove_bus(struct usb_bus *bus);
1232 extern void usbfs_add_device(struct usb_device *dev);
1233 extern void usbfs_remove_device(struct usb_device *dev);
1234 extern void usbfs_update_special (void);
1235
1236 extern int usbfs_init(void);
1237 extern void usbfs_cleanup(void);
1238
1239 #else /* CONFIG_USB_DEVICEFS */
1240
1241 static inline void usbfs_add_bus(struct usb_bus *bus) {}
1242 static inline void usbfs_remove_bus(struct usb_bus *bus) {}
1243 static inline void usbfs_add_device(struct usb_device *dev) {}
1244 static inline void usbfs_remove_device(struct usb_device *dev) {}
1245 static inline void usbfs_update_special (void) {}
1246
1247 static inline int usbfs_init(void) { return 0; }
1248 static inline void usbfs_cleanup(void) { }
1249
1250 #endif /* CONFIG_USB_DEVICEFS */
1251
1252 #endif  /* __KERNEL__ */
1253
1254 #endif