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