1 .. _usb-hostside-api:
2
3 ===========================
4 The Linux-USB Host Side API
5 ===========================
6
7 Introduction to USB on Linux
8 ============================
9
10 A Universal Serial Bus (USB) is used to connec
11 workstation, to a number of peripheral devices
12 structure, with the host as the root (the syst
13 interior nodes, and peripherals as leaves (and
14 support several such trees of USB devices, usu
15 a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s
16 USB 2.0 (480 MBit/s) busses just in case.
17
18 That master/slave asymmetry was designed-in fo
19 being ease of use. It is not physically possib
20 downstream or it does not matter with a type C
21 peripheral). Also, the host software doesn't n
22 distributed auto-configuration since the pre-d
23 manages all that.
24
25 Kernel developers added USB support to Linux e
26 series and have been developing it further sin
27 for each new generation of USB, various host c
28 new drivers for peripherals have been added an
29 measurement and improved power management intr
30
31 Linux can run inside USB devices as well as on
32 the devices. But USB device drivers running in
33 don't do the same things as the ones running i
34 been given a different name: *gadget drivers*.
35 cover gadget drivers.
36
37 USB Host-Side API Model
38 =======================
39
40 Host-side drivers for USB devices talk to the
41 two. One is intended for *general-purpose* dri
42 driver frameworks), and the other is for drive
43 core*. Such core drivers include the *hub* dri
44 of USB devices) and several different kinds of
45 drivers*, which control individual busses.
46
47 The device model seen by USB drivers is relati
48
49 - USB supports four kinds of data transfers (
50 and isochronous). Two of them (control and
51 it's available, while the other two (interr
52 scheduled to provide guaranteed bandwidth.
53
54 - The device description model includes one o
55 per device, only one of which is active at
56 to be capable of operating at lower than th
57 speeds and may provide a BOS descriptor sho
58 remain fully operational at.
59
60 - From USB 3.0 on configurations have one or
61 provide a common functionality and are grou
62 of power management.
63
64 - Configurations or functions have one or mor
65 "alternate settings". Interfaces may be sta
66 specifications, or may be specific to a ven
67
68 USB device drivers actually bind to interfa
69 them as "interface drivers", though you may
70 where the distinction is important. *Most U
71 with only one function, one configuration,
72 setting.*
73
74 - Interfaces have one or more "endpoints", ea
75 type and direction of data transfer such as
76 in". The entire configuration may have up t
77 each direction, allocated as needed among a
78
79 - Data transfer on USB is packetized; each en
80 packet size. Drivers must often be aware of
81 flagging the end of bulk transfers using "s
82 length) packets.
83
84 - The Linux USB API supports synchronous call
85 messages. It also supports asynchronous cal
86 transfer, using request structures called "
87 Blocks).
88
89 Accordingly, the USB Core API exposed to devic
90 lot of territory. You'll probably need to cons
91 specification, available online from www.usb.o
92 class or device specifications.
93
94 The only host-side drivers that actually touch
95 registers, handling IRQs, and so on) are the H
96 provide the same functionality through the sam
97 becoming more true, but there are still differ
98 that crop up especially with fault handling on
99 Different controllers don't
100 necessarily report the same aspects of failure
101 faults (including software-induced ones like u
102 fully consistent. Device driver authors should
103 disconnect testing (while the device is active
104 controller driver, to make sure drivers don't
105 well as to make sure they aren't relying on so
106
107 .. _usb_chapter9:
108
109 USB-Standard Types
110 ==================
111
112 In ``include/uapi/linux/usb/ch9.h`` you will f
113 in chapter 9 of the USB specification. These d
114 USB, and in APIs including this host side API,
115 devices and debugfs interfaces. That file is i
116 ``include/linux/usb/ch9.h``, which also contai
117 utility routines for manipulating these data t
118 are in ``drivers/usb/common/common.c``.
119
120 .. kernel-doc:: drivers/usb/common/common.c
121 :export:
122
123 In addition, some functions useful for creatin
124 defined in ``drivers/usb/common/debug.c``.
125
126 .. _usb_header:
127
128 Host-Side Data Types and Macros
129 ===============================
130
131 The host side API exposes several layers to dr
132 more necessary than others. These support life
133 drivers and devices, and support passing buffe
134 HCD that performs the I/O for the device drive
135
136 .. kernel-doc:: include/linux/usb.h
137 :internal:
138
139 USB Core APIs
140 =============
141
142 There are two basic I/O models in the USB API.
143 asynchronous: drivers submit requests in the f
144 URB's completion callback handles the next ste
145 support that model, although there are special
146 (which always have setup and status stages, bu
147 stage) and isochronous URBs (which allow large
148 per-packet fault reports). Built on top of tha
149 support, where a driver calls a routine that a
150 submits them, and waits until they complete. T
151 wrappers for single-buffer control and bulk tr
152 to use in some driver disconnect scenarios), a
153 streaming i/o (bulk or interrupt).
154
155 USB drivers need to provide buffers that can b
156 they don't necessarily need to provide the DMA
157 are APIs to use used when allocating DMA buffe
158 of bounce buffers on some systems. In some cas
159 rely on 64bit DMA to eliminate another kind of
160
161 .. kernel-doc:: drivers/usb/core/urb.c
162 :export:
163
164 .. kernel-doc:: drivers/usb/core/message.c
165 :export:
166
167 .. kernel-doc:: drivers/usb/core/file.c
168 :export:
169
170 .. kernel-doc:: drivers/usb/core/driver.c
171 :export:
172
173 .. kernel-doc:: drivers/usb/core/usb.c
174 :export:
175
176 .. kernel-doc:: drivers/usb/core/hub.c
177 :export:
178
179 Host Controller APIs
180 ====================
181
182 These APIs are only for use by host controller
183 implement standard register interfaces such as
184 was one of the first interfaces, designed by I
185 it doesn't do much in hardware. OHCI was desig
186 hardware do more work (bigger transfers, track
187 on). EHCI was designed with USB 2.0; its desig
188 resemble OHCI (hardware does much more work) a
189 of ISO support, TD list processing). XHCI was
190 continues to shift support for functionality i
191
192 There are host controllers other than the "big
193 based controllers (and a few non-PCI based one
194 interfaces. Not all host controllers use DMA;
195 also a simulator and a virtual host controller
196
197 The same basic APIs are available to drivers f
198 For historical reasons they are in two layers:
199 usb_bus <usb_bus>` is a rather thin layer that
200 in the 2.2 kernels, while :c:type:`struct usb_
201 is a more featureful layer
202 that lets HCDs share common code, to shrink dr
203 significantly reduce hcd-specific behaviors.
204
205 .. kernel-doc:: drivers/usb/core/hcd.c
206 :export:
207
208 .. kernel-doc:: drivers/usb/core/hcd-pci.c
209 :export:
210
211 .. kernel-doc:: drivers/usb/core/buffer.c
212 :internal:
213
214 The USB character device nodes
215 ==============================
216
217 This chapter presents the Linux character devi
218 to avoid writing new kernel code for your USB
219 drivers are usually packaged as applications o
220 character devices through some programming lib
221 Such libraries include:
222
223 - `libusb <http://libusb.sourceforge.net>`__
224 - `jUSB <http://jUSB.sourceforge.net>`__ for
225
226 Some old information about it can be seen at t
227 section of the USB Guide. The latest copy of t
228 at http://www.linux-usb.org/
229
230 .. note::
231
232 - They were used to be implemented via *usbf
233 the sysfs debug interface.
234
235 - This particular documentation is incomple
236 to the asynchronous mode. As of kernel 2.
237 (new) documentation need to be cross-revi
238
239 What files are in "devtmpfs"?
240 -----------------------------
241
242 Conventionally mounted at ``/dev/bus/usb/``, u
243
244 - ``/dev/bus/usb/BBB/DDD`` ... magic files ex
245 configuration descriptors, and supporting a
246 making device requests, including I/O to de
247 by programs.)
248
249 Each bus is given a number (``BBB``) based on
250 each bus, each device is given a similar numbe
251 paths are not "stable" identifiers; expect the
252 always leave the devices plugged in to the sam
253 think of saving these in application configura
254 identifiers are available, for user mode appli
255 them. HID and networking devices expose these
256 example you can be sure that you told the righ
257 second server. Pleast note that it doesn't (ye
258
259 /dev/bus/usb/BBB/DDD
260 --------------------
261
262 Use these files in one of these basic ways:
263
264 - *They can be read,* producing first the devi
265 then the descriptors for the current configu
266 for details about those binary data formats.
267 multibyte values from little endian format t
268 order, although a few of the fields in the d
269 the BCD-encoded fields, and the vendor and p
270 byteswapped for you. Note that configuration
271 descriptors for interfaces, altsettings, end
272 class descriptors.
273
274 - *Perform USB operations* using *ioctl()* req
275 requests (synchronously or asynchronously) o
276 requests need the ``CAP_SYS_RAWIO`` capabili
277 access permissions. Only one ioctl request c
278 device files at a time. This means that if y
279 an endpoint from one thread, you won't be ab
280 endpoint from another thread until the read
281 *half duplex* protocols, but otherwise you'd
282 requests.
283
284 Each connected USB device has one file. The `
285 number. The ``DDD`` indicates the device addr
286 of these numbers are assigned sequentially, an
287 you can't rely on them for stable access to de
288 it's relatively common for devices to re-enume
289 still connected (perhaps someone jostled their
290 or USB cable), so a device might be ``002/027`
291 it and ``002/048`` sometime later.
292
293 These files can be read as binary data. The b
294 of first the device descriptor, then the descr
295 configuration of the device. Multi-byte field
296 are converted to host endianness by the kernel
297 descriptors are in bus endian format! The conf
298 are wTotalLength bytes apart. If a device retu
299 descriptor data than indicated by wTotalLength
300 the file for the missing bytes. This informat
301 in text form by the ``/sys/kernel/debug/usb/de
302
303 These files may also be used to write user-lev
304 devices. You would open the ``/dev/bus/usb/BB
305 read its descriptors to make sure it's the dev
306 bind to an interface (or perhaps several) usin
307 would issue more ioctls to the device to commu
308 control, bulk, or other kinds of USB transfers
309 listed in the ``<linux/usbdevice_fs.h>`` file,
310 source code (``linux/drivers/usb/core/devio.c`
311 for how to access devices through those files.
312
313 Note that since by default these ``BBB/DDD`` f
314 root, only root can write such user mode drive
315 grant read/write permissions to other users by
316 usbfs mount options such as ``devmode=0666`` m
317
318
319 Life Cycle of User Mode Drivers
320 -------------------------------
321
322 Such a driver first needs to find a device fil
323 how to handle. Maybe it was told about it beca
324 event handling agent chose that driver to hand
325 maybe it's an application that scans all the `
326 and ignores most devices. In either case, it s
327 all the descriptors from the device file, and
328 knows how to handle. It might just reject ever
329 vendor and product ID, or need a more complex
330
331 Never assume there will only be one such devic
332 If your code can't handle more than one device
333 detect when there's more than one, and have yo
334 device to use.
335
336 Once your user mode driver knows what device t
337 it in either of two styles. The simple style i
338 requests; some devices don't need more complex
339 (An example might be software using vendor-spe
340 some initialization or configuration tasks, wi
341 rest.)
342
343 More likely, you need a more complex style dri
344 endpoints, reading or writing data and claimin
345 interface. *Bulk* transfers are easiest to use
346 *interrupt* transfers work with low speed devi
347 *isochronous* transfers offer service guarante
348 is reserved. Such "periodic" transfers are awk
349 unless you're using the asynchronous calls. Ho
350 can also be used in a synchronous "one shot" s
351
352 Your user-mode driver should never need to wor
353 request state when the device is disconnected,
354 its open file descriptors as soon as it starts
355
356 The ioctl() Requests
357 --------------------
358
359 To use these ioctls, you need to include the f
360 userspace program::
361
362 #include <linux/usb.h>
363 #include <linux/usbdevice_fs.h>
364 #include <asm/byteorder.h>
365
366 The standard USB device model requests, from "
367 specification, are automatically included from
368 header.
369
370 Unless noted otherwise, the ioctl requests des
371 the modification time on the usbfs file to whi
372 (unless they fail). A return of zero indicates
373 standard USB error code is returned (These are
374 :ref:`usb-error-codes`).
375
376 Each of these files multiplexes access to seve
377 endpoint. Each device has one control endpoint
378 supports a limited RPC style RPC access. Devic
379 hub_wq (in the kernel) setting a device-wide *
380 affects things like power consumption and basi
381 endpoints are part of USB *interfaces*, which
382 affecting things like which endpoints are avai
383 have a single configuration and interface, so
384 ignore configurations and altsettings.
385
386 Management/Status Requests
387 ~~~~~~~~~~~~~~~~~~~~~~~~~~
388
389 A number of usbfs requests don't deal very dir
390 They mostly relate to device management and st
391 synchronous requests.
392
393 USBDEVFS_CLAIMINTERFACE
394 This is used to force usbfs to claim a spe
395 not previously been claimed by usbfs or an
396 ioctl parameter is an integer holding the
397 (bInterfaceNumber from descriptor).
398
399 Note that if your driver doesn't claim an
400 use one of its endpoints, and no other dri
401 the interface is automatically claimed by
402
403 This claim will be released by a RELEASEIN
404 closing the file descriptor. File modifica
405 by this request.
406
407 USBDEVFS_CONNECTINFO
408 Says whether the device is lowspeed. The i
409 structure like this::
410
411 struct usbdevfs_connectinfo {
412 unsigned int devnum;
413 unsigned char slow;
414 };
415
416 File modification time is not updated by t
417
418 *You can't tell whether a "not slow" devic
419 speed (480 MBit/sec) or just full speed (1
420 know the devnum value already, it's the DD
421 name.
422
423 USBDEVFS_GET_SPEED
424 Returns the speed of the device. The speed
425 numerical value in accordance with enum us
426
427 File modification time is not updated by t
428
429 USBDEVFS_GETDRIVER
430 Returns the name of the kernel driver boun
431 string). Parameter is a pointer to this st
432 modified::
433
434 struct usbdevfs_getdriver {
435 unsigned int interface;
436 char driver[USBDEVFS_
437 };
438
439 File modification time is not updated by t
440
441 USBDEVFS_IOCTL
442 Passes a request from userspace through to
443 an ioctl entry in the *struct usb_driver*
444
445 struct usbdevfs_ioctl {
446 int ifno;
447 int ioctl_code;
448 void *data;
449 };
450
451 /* user mode call looks like this.
452 * 'request' becomes the driver->ioctl
453 * the size of 'param' is encoded in '
454 * is copied to or from the driver->io
455 */
456 static int
457 usbdev_ioctl (int fd, int ifno, unsign
458 {
459 struct usbdevfs_ioctl wrappe
460
461 wrapper.ifno = ifno;
462 wrapper.ioctl_code = request;
463 wrapper.data = param;
464
465 return ioctl (fd, USBDEVFS_IOC
466 }
467
468 File modification time is not updated by t
469
470 This request lets kernel drivers talk to u
471 filesystem operations even when they don't
472 block special device. It's also been used
473 devices what device special file should be
474 ioctls are used to disconnect and reconnec
475 user mode code can completely manage bindi
476 devices.
477
478 USBDEVFS_RELEASEINTERFACE
479 This is used to release the claim usbfs ma
480 implicitly or because of a USBDEVFS_CLAIMI
481 file descriptor is closed. The ioctl param
482 the number of the interface (bInterfaceNum
483 modification time is not updated by this r
484
485 .. warning::
486
487 *No security check is made to ensure t
488 the claim is the one which is releasin
489 mode driver may interfere other ones.*
490
491 USBDEVFS_RESETEP
492 Resets the data toggle value for an endpoi
493 DATA0. The ioctl parameter is an integer e
494 as identified in the endpoint descriptor),
495 if the device's endpoint sends data to the
496
497 .. Warning::
498
499 *Avoid using this request. It should p
500 it typically means the device and driv
501 synchronization. If you really lost sy
502 need to completely handshake with the
503 like CLEAR_HALT or SET_INTERFACE.
504
505 USBDEVFS_DROP_PRIVILEGES
506 This is used to relinquish the ability to
507 which are considered to be privileged on a
508 This includes claiming arbitrary interface
509 which there are currently claimed interfac
510 issuing USBDEVFS_IOCTL calls. The ioctl pa
511 of interfaces the user is allowed to claim
512 You may issue this ioctl more than one tim
513
514 Synchronous I/O Support
515 ~~~~~~~~~~~~~~~~~~~~~~~
516
517 Synchronous requests involve the kernel blocki
518 request completes, either by finishing success
519 error. In most cases this is the simplest way
520 noted above it does prevent performing I/O to
521 a time.
522
523 USBDEVFS_BULK
524 Issues a bulk read or write request to the
525 parameter is a pointer to this structure::
526
527 struct usbdevfs_bulktransfer {
528 unsigned int ep;
529 unsigned int len;
530 unsigned int timeout; /* in m
531 void *data;
532 };
533
534 The ``ep`` value identifies a bulk endpoin
535 identified in an endpoint descriptor), mas
536 referring to an endpoint which sends data
537 device. The length of the data buffer is i
538 kernels support requests up to about 128KB
539 length is returned, and how short reads ar
540
541 USBDEVFS_CLEAR_HALT
542 Clears endpoint halt (stall) and resets th
543 only meaningful for bulk or interrupt endp
544 is an integer endpoint number (1 to 15, as
545 descriptor), masked with USB_DIR_IN when r
546 which sends data to the host from the devi
547
548 Use this on bulk or interrupt endpoints wh
549 returning ``-EPIPE`` status to a data tran
550 the control request directly, since that c
551 record of the data toggle.
552
553 USBDEVFS_CONTROL
554 Issues a control request to the device. Th
555 to a structure like this::
556
557 struct usbdevfs_ctrltransfer {
558 __u8 bRequestType;
559 __u8 bRequest;
560 __u16 wValue;
561 __u16 wIndex;
562 __u16 wLength;
563 __u32 timeout; /* in millise
564 void *data;
565 };
566
567 The first eight bytes of this structure ar
568 SETUP packet to be sent to the device; see
569 for details. The bRequestType value is com
570 ``USB_TYPE_*`` value, a ``USB_DIR_*`` valu
571 value (from ``linux/usb.h``). If wLength i
572 the length of the data buffer, which is ei
573 (USB_DIR_OUT) or read from the device (USB
574
575 At this writing, you can't transfer more t
576 from a device; usbfs has a limit, and some
577 have a limit. (That's not usually a proble
578 to say it's not OK to get a short read bac
579
580 USBDEVFS_RESET
581 Does a USB level device reset. The ioctl p
582 the reset, this rebinds all device interfa
583 time is not updated by this request.
584
585 .. warning::
586
587 *Avoid using this call* until some usb
588 it does not fully synchronize device,
589 just usbfs) state.
590
591 USBDEVFS_SETINTERFACE
592 Sets the alternate setting for an interfac
593 a pointer to a structure like this::
594
595 struct usbdevfs_setinterface {
596 unsigned int interface;
597 unsigned int altsetting;
598 };
599
600 File modification time is not updated by t
601
602 Those struct members are from some interfa
603 the current configuration. The interface n
604 bInterfaceNumber value, and the altsetting
605 bAlternateSetting value. (This resets each
606 interface.)
607
608 USBDEVFS_SETCONFIGURATION
609 Issues the :c:func:`usb_set_configuration(
610 device. The parameter is an integer holdin
611 configuration (bConfigurationValue from de
612 modification time is not updated by this r
613
614 .. warning::
615
616 *Avoid using this call* until some usb
617 it does not fully synchronize device,
618 just usbfs) state.
619
620 Asynchronous I/O Support
621 ~~~~~~~~~~~~~~~~~~~~~~~~
622
623 As mentioned above, there are situations where
624 initiate concurrent operations from user mode
625 important for periodic transfers (interrupt an
626 be used for other kinds of USB requests too. I
627 asynchronous requests described here are essen
628 submitting one request and having the kernel b
629 the blocking is separate.
630
631 These requests are packaged into a structure t
632 by kernel device drivers. (No POSIX Async I/O
633 identifies the endpoint type (``USBDEVFS_URB_T
634 (number, masked with USB_DIR_IN as appropriate
635 and a user "context" value serving to uniquely
636 (It's usually a pointer to per-request data.)
637 (not as many as supported for kernel drivers).
638
639 Each request can specify a realtime signal num
640 SIGRTMAX, inclusive) to request a signal be se
641 completes.
642
643 When usbfs returns these urbs, the status valu
644 buffer may have been modified. Except for isoc
645 actual_length is updated to say how many bytes
646 USBDEVFS_URB_DISABLE_SPD flag is set ("short p
647 fewer bytes were read than were requested then
648
649 struct usbdevfs_iso_packet_desc {
650 unsigned int l
651 unsigned int a
652 unsigned int s
653 };
654
655 struct usbdevfs_urb {
656 unsigned char t
657 unsigned char e
658 int s
659 unsigned int f
660 void *
661 int b
662 int a
663 int s
664 int n
665 int e
666 unsigned int s
667 void *
668 struct usbdevfs_iso_packet_desc i
669 };
670
671 For these asynchronous requests, the file modi
672 when the request was initiated. This contrasts
673 synchronous requests, where it reflects when r
674
675 USBDEVFS_DISCARDURB
676 *TBS* File modification time is not update
677
678 USBDEVFS_DISCSIGNAL
679 *TBS* File modification time is not update
680
681 USBDEVFS_REAPURB
682 *TBS* File modification time is not update
683
684 USBDEVFS_REAPURBNDELAY
685 *TBS* File modification time is not update
686
687 USBDEVFS_SUBMITURB
688 *TBS*
689
690 The USB devices
691 ===============
692
693 The USB devices are now exported via debugfs:
694
695 - ``/sys/kernel/debug/usb/devices`` ... a tex
696 devices on known to the kernel, and their c
697 You can also poll() this to learn about new
698
699 /sys/kernel/debug/usb/devices
700 -----------------------------
701
702 This file is handy for status viewing tools in
703 the text format and ignore most of it. More de
704 (including class and vendor status) is availab
705 files. For information about the current forma
706
707 This file, in combination with the poll() syst
708 to detect when devices are added or removed::
709
710 int fd;
711 struct pollfd pfd;
712
713 fd = open("/sys/kernel/debug/usb/devices",
714 pfd = { fd, POLLIN, 0 };
715 for (;;) {
716 /* The first time through, this call w
717 poll(&pfd, 1, -1);
718
719 /* To see what's changed, compare the
720 contents or scan the filesystem. (
721 }
722
723 Note that this behavior is intended to be used
724 debug purposes. It would be more appropriate t
725 udev or HAL to initialize a device or start a
726 for instance.
727
728 In this file, each device's output has multipl
729
730 I made it ASCII instead of binary on purpose,
731 can obtain some useful data from it without th
732 auxiliary program. However, with an auxiliary
733 in the first 4 columns of each ``T:`` line (to
734 Lev, Prnt, Port, Cnt) can be used to build a U
735
736 Each line is tagged with a one-character ID fo
737
738 T = Topology (etc.)
739 B = Bandwidth (applies only to USB hos
740 virtualized as root hubs)
741 D = Device descriptor info.
742 P = Product ID info. (from Device desc
743 together on one line)
744 S = String descriptors.
745 C = Configuration descriptor info. (*
746 I = Interface descriptor info.
747 E = Endpoint descriptor info.
748
749 /sys/kernel/debug/usb/devices output format
750 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
751
752 Legend::
753 d = decimal number (may have leading spaces
754 x = hexadecimal number (may have leading spa
755 s = string
756
757
758
759 Topology info
760 ^^^^^^^^^^^^^
761
762 ::
763
764 T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=
765 | | | | | |
766 | | | | | |
767 | | | | | |
768 | | | | | |__C
769 | | | | |__Connector
770 | | | |__Parent DeviceNumb
771 | | |__Level in topology for th
772 | |__Bus number
773 |__Topology info tag
774
775 Speed may be:
776
777 ======= ==============================
778 1.5 Mbit/s for low speed USB
779 12 Mbit/s for full speed USB
780 480 Mbit/s for high speed USB (add
781 5000 Mbit/s for SuperSpeed USB (add
782 ======= ==============================
783
784 For reasons lost in the mists of time, the Por
785 too low by 1. For example, a device plugged i
786 show up with ``Port=03``.
787
788 Bandwidth info
789 ^^^^^^^^^^^^^^
790
791 ::
792
793 B: Alloc=ddd/ddd us (xx%), #Int=ddd,
794 | | |
795 | | |__Number
796 | |__Total Bandwidth allocated to th
797 |__Bandwidth info tag
798
799 Bandwidth allocation is an approximation of ho
800 (millisecond) is in use. It reflects only per
801 are the only transfers that reserve bandwidth.
802 transfers use all other bandwidth, including r
803 is not used for transfers (such as for short p
804
805 The percentage is how much of the "reserved" b
806 those transfers. For a low or full speed bus
807 90% of the bus bandwidth is reserved. For a h
808 "USB 2.0") 80% is reserved.
809
810
811 Device descriptor info & Product ID info
812 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
813
814 ::
815
816 D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx
817 P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
818
819 where::
820
821 D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot
822 | | | | |
823 | | | | |
824 | | | | |__D
825 | | | |__DeviceSu
826 | | |__DeviceClass
827 | |__Device USB version
828 |__Device info tag #1
829
830 where::
831
832 P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
833 | | | |__Product
834 | | |__Product ID code
835 | |__Vendor ID code
836 |__Device info tag #2
837
838
839 String descriptor info
840 ^^^^^^^^^^^^^^^^^^^^^^
841 ::
842
843 S: Manufacturer=ssss
844 | |__Manufacturer of this device as
845 | For USB host controller drivers
846 | be omitted, or (for newer drive
847 | version and the driver which pr
848 |__String info tag
849
850 S: Product=ssss
851 | |__Product description of this dev
852 | For older USB host controller d
853 | indicates the driver; for newer
854 | description that often comes fr
855 |__String info tag
856
857 S: SerialNumber=ssss
858 | |__Serial Number of this device as
859 | For USB host controller drivers
860 | some unique ID, normally a bus
861 | can't be shared with any other
862 |__String info tag
863
864
865
866 Configuration descriptor info
867 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
868 ::
869
870 C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
871 | | | | | |__MaxPower
872 | | | | |__Attributes
873 | | | |__ConfiguratioNumber
874 | | |__NumberOfInterfaces
875 | |__ "*" indicates the active configu
876 |__Config info tag
877
878 USB devices may have multiple configurations,
879 rather differently. For example, a bus-powere
880 might be much less capable than one that is se
881 one device configuration can be active at a ti
882 have only one configuration.
883
884 Each configuration consists of one or more int
885 interface serves a distinct "function", which
886 to a different USB device driver. One common
887 speaker with an audio interface for playback,
888 for use with software volume control.
889
890 Interface descriptor info (can be multiple per
891 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
892 ::
893
894 I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss
895 | | | | | |
896 | | | | | |
897 | | | | | |
898 | | | | | |
899 | | | | | |__Interface
900 | | | | |__NumberOfEndpoints
901 | | | |__AlternateSettingNumber
902 | | |__InterfaceNumber
903 | |__ "*" indicates the active altsett
904 |__Interface info tag
905
906 A given interface may have one or more "altern
907 For example, default settings may not use more
908 amount of periodic bandwidth. To use signific
909 of bus bandwidth, drivers must select a non-de
910
911 Only one setting for an interface may be activ
912 only one driver may bind to an interface at a
913 have only one alternate setting per interface.
914
915
916 Endpoint descriptor info (can be multiple per
917 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
918
919 ::
920
921 E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Iv
922 | | | | |_
923 | | | |__EndpointM
924 | | |__Attributes(EndpointTyp
925 | |__EndpointAddress(I=In,O=Out)
926 |__Endpoint info tag
927
928 The interval is nonzero for all periodic (inte
929 endpoints. For high speed endpoints the trans
930 measured in microseconds rather than milliseco
931
932 For high speed periodic endpoints, the ``Endpo
933 the per-microframe data transfer size. For "h
934 endpoints, that can reflect two or three packe
935 3KBytes every 125 usec) per endpoint.
936
937 With the Linux-USB stack, periodic bandwidth r
938 transfer intervals and sizes provided by URBs,
939 than those found in endpoint descriptor.
940
941 Usage examples
942 ~~~~~~~~~~~~~~
943
944 If a user or script is interested only in Topo
945 example, use something like ``grep ^T: /sys/ke
946 for only the Topology lines. A command like
947 ``grep -i ^[tdp]: /sys/kernel/debug/usb/device
948 only the lines that begin with the characters
949 where the valid characters are TDPCIE. With a
950 script, it can display any selected lines (for
951 and P lines) and change their output format.
952 Perl script is the beginning of this idea. It
953 selected lines [selected from TBDPSCIE] or "Al
954 ``/sys/kernel/debug/usb/devices``.)
955
956 The Topology lines can be used to generate a g
957 of the USB devices on a system's root hub. (S
958 on how to do this.)
959
960 The Interface lines can be used to determine w
961 being used for each device, and which altsetti
962
963 The Configuration lines could be used to list
964 (in milliamps) that a system's USB devices are
965 For example, ``grep ^C: /sys/kernel/debug/usb/
966
967
968 Here's an example, from a system which has a U
969 an external hub connected to the root hub, and
970 a serial converter connected to the external h
971
972 ::
973
974 T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=
975 B: Alloc= 28/900 us ( 3%), #Int= 2,
976 D: Ver= 1.00 Cls=09(hub ) Sub=00 Pro
977 P: Vendor=0000 ProdID=0000 Rev= 0.00
978 S: Product=USB UHCI Root Hub
979 S: SerialNumber=dce0
980 C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
981 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub
982 E: Ad=81(I) Atr=03(Int.) MxPS= 8 Iv
983
984 T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=
985 D: Ver= 1.00 Cls=09(hub ) Sub=00 Pro
986 P: Vendor=0451 ProdID=1446 Rev= 1.00
987 C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
988 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub
989 E: Ad=81(I) Atr=03(Int.) MxPS= 1 Iv
990
991 T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=
992 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Pro
993 P: Vendor=04b4 ProdID=0001 Rev= 0.00
994 C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
995 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID
996 E: Ad=81(I) Atr=03(Int.) MxPS= 3 Iv
997
998 T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=
999 D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Pro
1000 P: Vendor=0565 ProdID=0001 Rev= 1.08
1001 S: Manufacturer=Peracom Networks, In
1002 S: Product=Peracom USB to Serial Con
1003 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100m
1004 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc
1005 E: Ad=81(I) Atr=02(Bulk) MxPS= 64 I
1006 E: Ad=01(O) Atr=02(Bulk) MxPS= 16 I
1007 E: Ad=82(I) Atr=03(Int.) MxPS= 8 I
1008
1009
1010 Selecting only the ``T:`` and ``I:`` lines fr
1011 ``procusb ti``), we have
1012
1013 ::
1014
1015 T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt
1016 T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt
1017 I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub
1018 T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt
1019 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID
1020 T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt
1021 I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc
1022
1023
1024 Physically this looks like (or could be conve
1025
1026 +------------------+
1027 | PC/root_hub (12)|
1028 +------------------+
1029 Level 0 | CN.0 | CN.1 |
1030 +------------------+
1031 /
1032 /
1033 +-----------------------+
1034 Level 1 | Dev#2: 4-port hub (12)|
1035 +-----------------------+
1036 |CN.0 |CN.1 |CN.2 |CN.3 |
1037 +-----------------------+
1038 \ \________________
1039 \_____
1040 \
1041 +--------------------+ +-
1042 Level 2 | Dev# 3: mouse (1.5)| |
1043 +--------------------+ +-
1044
1045
1046
1047 Or, in a more tree-like structure (ports [Con
1048 connections could be omitted)::
1049
1050 PC: Dev# 1, root hub, 2 ports, 12 Mb
1051 |_ CN.0: Dev# 2, hub, 4 ports, 12 Mb
1052 |_ CN.0: Dev #3, mouse, 1.5 Mbp
1053 |_ CN.1:
1054 |_ CN.2: Dev #4, serial, 12 Mbp
1055 |_ CN.3:
1056 |_ CN.1:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.