Documentation/usb/gadget-testing.rst

   1 ==============
   2 Gadget Testing
   3 ==============
   4
   5 This file summarizes information on basic testing of USB functions
   6 provided by gadgets.
   7
   8 .. contents
   9
  10    1. ACM function
  11    2. ECM function
  12    3. ECM subset function
  13    4. EEM function
  14    5. FFS function
  15    6. HID function
  16    7. LOOPBACK function
  17    8. MASS STORAGE function
  18    9. MIDI function
  19    10. NCM function
  20    11. OBEX function
  21    12. PHONET function
  22    13. RNDIS function
  23    14. SERIAL function
  24    15. SOURCESINK function
  25    16. UAC1 function (legacy implementation)
  26    17. UAC2 function
  27    18. UVC function
  28    19. PRINTER function
  29    20. UAC1 function (new API)
  30    21. MIDI2 function
  31
  32
  33 1. ACM function
  34 ===============
  35
  36 The function is provided by usb_f_acm.ko module.
  37
  38 Function-specific configfs interface
  39 ------------------------------------
  40
  41 The function name to use when creating the function directory is "acm".
  42 The ACM function provides just one attribute in its function directory:
  43
  44         port_num
  45
  46 The attribute is read-only.
  47
  48 There can be at most 4 ACM/generic serial/OBEX ports in the system.
  49
  50
  51 Testing the ACM function
  52 ------------------------
  53
  54 On the host::
  55
  56         cat > /dev/ttyACM<X>
  57
  58 On the device::
  59
  60         cat /dev/ttyGS<Y>
  61
  62 then the other way round
  63
  64 On the device::
  65
  66         cat > /dev/ttyGS<Y>
  67
  68 On the host::
  69
  70         cat /dev/ttyACM<X>
  71
  72 2. ECM function
  73 ===============
  74
  75 The function is provided by usb_f_ecm.ko module.
  76
  77 Function-specific configfs interface
  78 ------------------------------------
  79
  80 The function name to use when creating the function directory is "ecm".
  81 The ECM function provides these attributes in its function directory:
  82
  83         =============== ==================================================
  84         ifname          network device interface name associated with this
  85                         function instance
  86         qmult           queue length multiplier for high and super speed
  87         host_addr       MAC address of host's end of this
  88                         Ethernet over USB link
  89         dev_addr        MAC address of device's end of this
  90                         Ethernet over USB link
  91         =============== ==================================================
  92
  93 and after creating the functions/ecm.<instance name> they contain default
  94 values: qmult is 5, dev_addr and host_addr are randomly selected.
  95 The ifname can be written to if the function is not bound. A write must be an
  96 interface pattern such as "usb%d", which will cause the net core to choose the
  97 next free usbX interface. By default, it is set to "usb%d".
  98
  99 Testing the ECM function
 100 ------------------------
 101
 102 Configure IP addresses of the device and the host. Then:
 103
 104 On the device::
 105
 106         ping <host's IP>
 107
 108 On the host::
 109
 110         ping <device's IP>
 111
 112 3. ECM subset function
 113 ======================
 114
 115 The function is provided by usb_f_ecm_subset.ko module.
 116
 117 Function-specific configfs interface
 118 ------------------------------------
 119
 120 The function name to use when creating the function directory is "geth".
 121 The ECM subset function provides these attributes in its function directory:
 122
 123         =============== ==================================================
 124         ifname          network device interface name associated with this
 125                         function instance
 126         qmult           queue length multiplier for high and super speed
 127         host_addr       MAC address of host's end of this
 128                         Ethernet over USB link
 129         dev_addr        MAC address of device's end of this
 130                         Ethernet over USB link
 131         =============== ==================================================
 132
 133 and after creating the functions/ecm.<instance name> they contain default
 134 values: qmult is 5, dev_addr and host_addr are randomly selected.
 135 The ifname can be written to if the function is not bound. A write must be an
 136 interface pattern such as "usb%d", which will cause the net core to choose the
 137 next free usbX interface. By default, it is set to "usb%d".
 138
 139 Testing the ECM subset function
 140 -------------------------------
 141
 142 Configure IP addresses of the device and the host. Then:
 143
 144 On the device::
 145
 146         ping <host's IP>
 147
 148 On the host::
 149
 150         ping <device's IP>
 151
 152 4. EEM function
 153 ===============
 154
 155 The function is provided by usb_f_eem.ko module.
 156
 157 Function-specific configfs interface
 158 ------------------------------------
 159
 160 The function name to use when creating the function directory is "eem".
 161 The EEM function provides these attributes in its function directory:
 162
 163         =============== ==================================================
 164         ifname          network device interface name associated with this
 165                         function instance
 166         qmult           queue length multiplier for high and super speed
 167         host_addr       MAC address of host's end of this
 168                         Ethernet over USB link
 169         dev_addr        MAC address of device's end of this
 170                         Ethernet over USB link
 171         =============== ==================================================
 172
 173 and after creating the functions/eem.<instance name> they contain default
 174 values: qmult is 5, dev_addr and host_addr are randomly selected.
 175 The ifname can be written to if the function is not bound. A write must be an
 176 interface pattern such as "usb%d", which will cause the net core to choose the
 177 next free usbX interface. By default, it is set to "usb%d".
 178
 179 Testing the EEM function
 180 ------------------------
 181
 182 Configure IP addresses of the device and the host. Then:
 183
 184 On the device::
 185
 186         ping <host's IP>
 187
 188 On the host::
 189
 190         ping <device's IP>
 191
 192 5. FFS function
 193 ===============
 194
 195 The function is provided by usb_f_fs.ko module.
 196
 197 Function-specific configfs interface
 198 ------------------------------------
 199
 200 The function name to use when creating the function directory is "ffs".
 201 The function directory is intentionally empty and not modifiable.
 202
 203 After creating the directory there is a new instance (a "device") of FunctionFS
 204 available in the system. Once a "device" is available, the user should follow
 205 the standard procedure for using FunctionFS (mount it, run the userspace
 206 process which implements the function proper). The gadget should be enabled
 207 by writing a suitable string to usb_gadget/<gadget>/UDC.
 208
 209 Testing the FFS function
 210 ------------------------
 211
 212 On the device: start the function's userspace daemon, enable the gadget
 213
 214 On the host: use the USB function provided by the device
 215
 216 6. HID function
 217 ===============
 218
 219 The function is provided by usb_f_hid.ko module.
 220
 221 Function-specific configfs interface
 222 ------------------------------------
 223
 224 The function name to use when creating the function directory is "hid".
 225 The HID function provides these attributes in its function directory:
 226
 227         =============== ===========================================
 228         protocol        HID protocol to use
 229         report_desc     data to be used in HID reports, except data
 230                         passed with /dev/hidg<X>
 231         report_length   HID report length
 232         subclass        HID subclass to use
 233         =============== ===========================================
 234
 235 For a keyboard the protocol and the subclass are 1, the report_length is 8,
 236 while the report_desc is::
 237
 238   $ hd my_report_desc
 239   00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
 240   00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
 241   00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
 242   00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
 243   0000003f
 244
 245 Such a sequence of bytes can be stored to the attribute with echo::
 246
 247   $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
 248
 249 Testing the HID function
 250 ------------------------
 251
 252 Device:
 253
 254 - create the gadget
 255 - connect the gadget to a host, preferably not the one used
 256   to control the gadget
 257 - run a program which writes to /dev/hidg<N>, e.g.
 258   a userspace program found in Documentation/usb/gadget_hid.rst::
 259
 260         $ ./hid_gadget_test /dev/hidg0 keyboard
 261
 262 Host:
 263
 264 - observe the keystrokes from the gadget
 265
 266 7. LOOPBACK function
 267 ====================
 268
 269 The function is provided by usb_f_ss_lb.ko module.
 270
 271 Function-specific configfs interface
 272 ------------------------------------
 273
 274 The function name to use when creating the function directory is "Loopback".
 275 The LOOPBACK function provides these attributes in its function directory:
 276
 277         =============== =======================
 278         qlen            depth of loopback queue
 279         bulk_buflen     buffer length
 280         =============== =======================
 281
 282 Testing the LOOPBACK function
 283 -----------------------------
 284
 285 device: run the gadget
 286
 287 host: test-usb (tools/usb/testusb.c)
 288
 289 8. MASS STORAGE function
 290 ========================
 291
 292 The function is provided by usb_f_mass_storage.ko module.
 293
 294 Function-specific configfs interface
 295 ------------------------------------
 296
 297 The function name to use when creating the function directory is "mass_storage".
 298 The MASS STORAGE function provides these attributes in its directory:
 299 files:
 300
 301         =============== ==============================================
 302         stall           Set to permit function to halt bulk endpoints.
 303                         Disabled on some USB devices known not to work
 304                         correctly. You should set it to true.
 305         num_buffers     Number of pipeline buffers. Valid numbers
 306                         are 2..4. Available only if
 307                         CONFIG_USB_GADGET_DEBUG_FILES is set.
 308         =============== ==============================================
 309
 310 and a default lun.0 directory corresponding to SCSI LUN #0.
 311
 312 A new lun can be added with mkdir::
 313
 314         $ mkdir functions/mass_storage.0/partition.5
 315
 316 Lun numbering does not have to be continuous, except for lun #0 which is
 317 created by default. A maximum of 8 luns can be specified and they all must be
 318 named following the <name>.<number> scheme. The numbers can be 0..8.
 319 Probably a good convention is to name the luns "lun.<number>",
 320 although it is not mandatory.
 321
 322 In each lun directory there are the following attribute files:
 323
 324         =============== ==============================================
 325         file            The path to the backing file for the LUN.
 326                         Required if LUN is not marked as removable.
 327         ro              Flag specifying access to the LUN shall be
 328                         read-only. This is implied if CD-ROM emulation
 329                         is enabled as well as when it was impossible
 330                         to open "filename" in R/W mode.
 331         removable       Flag specifying that LUN shall be indicated as
 332                         being removable.
 333         cdrom           Flag specifying that LUN shall be reported as
 334                         being a CD-ROM.
 335         nofua           Flag specifying that FUA flag
 336                         in SCSI WRITE(10,12)
 337         forced_eject    This write-only file is useful only when
 338                         the function is active. It causes the backing
 339                         file to be forcibly detached from the LUN,
 340                         regardless of whether the host has allowed it.
 341                         Any non-zero number of bytes written will
 342                         result in ejection.
 343         =============== ==============================================
 344
 345 Testing the MASS STORAGE function
 346 ---------------------------------
 347
 348 device: connect the gadget, enable it
 349 host: dmesg, see the USB drives appear (if system configured to automatically
 350 mount)
 351
 352 9. MIDI function
 353 ================
 354
 355 The function is provided by usb_f_midi.ko module.
 356
 357 Function-specific configfs interface
 358 ------------------------------------
 359
 360 The function name to use when creating the function directory is "midi".
 361 The MIDI function provides these attributes in its function directory:
 362
 363         =============== ====================================
 364         buflen          MIDI buffer length
 365         id              ID string for the USB MIDI adapter
 366         in_ports        number of MIDI input ports
 367         index           index value for the USB MIDI adapter
 368         out_ports       number of MIDI output ports
 369         qlen            USB read request queue length
 370         =============== ====================================
 371
 372 Testing the MIDI function
 373 -------------------------
 374
 375 There are two cases: playing a mid from the gadget to
 376 the host and playing a mid from the host to the gadget.
 377
 378 1) Playing a mid from the gadget to the host:
 379
 380 host::
 381
 382   $ arecordmidi -l
 383    Port    Client name                      Port name
 384    14:0    Midi Through                     Midi Through Port-0
 385    24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 386   $ arecordmidi -p 24:0 from_gadget.mid
 387
 388 gadget::
 389
 390   $ aplaymidi -l
 391    Port    Client name                      Port name
 392    20:0    f_midi                           f_midi
 393
 394   $ aplaymidi -p 20:0 to_host.mid
 395
 396 2) Playing a mid from the host to the gadget
 397
 398 gadget::
 399
 400   $ arecordmidi -l
 401    Port    Client name                      Port name
 402    20:0    f_midi                           f_midi
 403
 404   $ arecordmidi -p 20:0 from_host.mid
 405
 406 host::
 407
 408   $ aplaymidi -l
 409    Port    Client name                      Port name
 410    14:0    Midi Through                     Midi Through Port-0
 411    24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 412
 413   $ aplaymidi -p24:0 to_gadget.mid
 414
 415 The from_gadget.mid should sound identical to the to_host.mid.
 416
 417 The from_host.id should sound identical to the to_gadget.mid.
 418
 419 MIDI files can be played to speakers/headphones with e.g. timidity installed::
 420
 421   $ aplaymidi -l
 422    Port    Client name                      Port name
 423    14:0    Midi Through                     Midi Through Port-0
 424    24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 425   128:0    TiMidity                         TiMidity port 0
 426   128:1    TiMidity                         TiMidity port 1
 427   128:2    TiMidity                         TiMidity port 2
 428   128:3    TiMidity                         TiMidity port 3
 429
 430   $ aplaymidi -p 128:0 file.mid
 431
 432 MIDI ports can be logically connected using the aconnect utility, e.g.::
 433
 434   $ aconnect 24:0 128:0 # try it on the host
 435
 436 After the gadget's MIDI port is connected to timidity's MIDI port,
 437 whatever is played at the gadget side with aplaymidi -l is audible
 438 in host's speakers/headphones.
 439
 440 10. NCM function
 441 ================
 442
 443 The function is provided by usb_f_ncm.ko module.
 444
 445 Function-specific configfs interface
 446 ------------------------------------
 447
 448 The function name to use when creating the function directory is "ncm".
 449 The NCM function provides these attributes in its function directory:
 450
 451         =============== ==================================================
 452         ifname          network device interface name associated with this
 453                         function instance
 454         qmult           queue length multiplier for high and super speed
 455         host_addr       MAC address of host's end of this
 456                         Ethernet over USB link
 457         dev_addr        MAC address of device's end of this
 458                         Ethernet over USB link
 459         =============== ==================================================
 460
 461 and after creating the functions/ncm.<instance name> they contain default
 462 values: qmult is 5, dev_addr and host_addr are randomly selected.
 463 The ifname can be written to if the function is not bound. A write must be an
 464 interface pattern such as "usb%d", which will cause the net core to choose the
 465 next free usbX interface. By default, it is set to "usb%d".
 466
 467 Testing the NCM function
 468 ------------------------
 469
 470 Configure IP addresses of the device and the host. Then:
 471
 472 On the device::
 473
 474         ping <host's IP>
 475
 476 On the host::
 477
 478         ping <device's IP>
 479
 480 11. OBEX function
 481 =================
 482
 483 The function is provided by usb_f_obex.ko module.
 484
 485 Function-specific configfs interface
 486 ------------------------------------
 487
 488 The function name to use when creating the function directory is "obex".
 489 The OBEX function provides just one attribute in its function directory:
 490
 491         port_num
 492
 493 The attribute is read-only.
 494
 495 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 496
 497 Testing the OBEX function
 498 -------------------------
 499
 500 On device::
 501
 502         seriald -f /dev/ttyGS<Y> -s 1024
 503
 504 On host::
 505
 506         serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
 507                 -t<out endpoint addr> -r<in endpoint addr>
 508
 509 where seriald and serialc are Felipe's utilities found here:
 510
 511         https://github.com/felipebalbi/usb-tools.git master
 512
 513 12. PHONET function
 514 ===================
 515
 516 The function is provided by usb_f_phonet.ko module.
 517
 518 Function-specific configfs interface
 519 ------------------------------------
 520
 521 The function name to use when creating the function directory is "phonet".
 522 The PHONET function provides just one attribute in its function directory:
 523
 524         =============== ==================================================
 525         ifname          network device interface name associated with this
 526                         function instance
 527         =============== ==================================================
 528
 529 Testing the PHONET function
 530 ---------------------------
 531
 532 It is not possible to test the SOCK_STREAM protocol without a specific piece
 533 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
 534 in the past I had to apply the patch mentioned here:
 535
 536 http://www.spinics.net/lists/linux-usb/msg85689.html
 537
 538 These tools are required:
 539
 540 git://git.gitorious.org/meego-cellular/phonet-utils.git
 541
 542 On the host::
 543
 544         $ ./phonet -a 0x10 -i usbpn0
 545         $ ./pnroute add 0x6c usbpn0
 546         $./pnroute add 0x10 usbpn0
 547         $ ifconfig usbpn0 up
 548
 549 On the device::
 550
 551         $ ./phonet -a 0x6c -i upnlink0
 552         $ ./pnroute add 0x10 upnlink0
 553         $ ifconfig upnlink0 up
 554
 555 Then a test program can be used::
 556
 557         http://www.spinics.net/lists/linux-usb/msg85690.html
 558
 559 On the device::
 560
 561         $ ./pnxmit -a 0x6c -r
 562
 563 On the host::
 564
 565         $ ./pnxmit -a 0x10 -s 0x6c
 566
 567 As a result some data should be sent from host to device.
 568 Then the other way round:
 569
 570 On the host::
 571
 572         $ ./pnxmit -a 0x10 -r
 573
 574 On the device::
 575
 576         $ ./pnxmit -a 0x6c -s 0x10
 577
 578 13. RNDIS function
 579 ==================
 580
 581 The function is provided by usb_f_rndis.ko module.
 582
 583 Function-specific configfs interface
 584 ------------------------------------
 585
 586 The function name to use when creating the function directory is "rndis".
 587 The RNDIS function provides these attributes in its function directory:
 588
 589         =============== ==================================================
 590         ifname          network device interface name associated with this
 591                         function instance
 592         qmult           queue length multiplier for high and super speed
 593         host_addr       MAC address of host's end of this
 594                         Ethernet over USB link
 595         dev_addr        MAC address of device's end of this
 596                         Ethernet over USB link
 597         =============== ==================================================
 598
 599 and after creating the functions/rndis.<instance name> they contain default
 600 values: qmult is 5, dev_addr and host_addr are randomly selected.
 601 The ifname can be written to if the function is not bound. A write must be an
 602 interface pattern such as "usb%d", which will cause the net core to choose the
 603 next free usbX interface. By default, it is set to "usb%d".
 604
 605 Testing the RNDIS function
 606 --------------------------
 607
 608 Configure IP addresses of the device and the host. Then:
 609
 610 On the device::
 611
 612         ping <host's IP>
 613
 614 On the host::
 615
 616         ping <device's IP>
 617
 618 14. SERIAL function
 619 ===================
 620
 621 The function is provided by usb_f_gser.ko module.
 622
 623 Function-specific configfs interface
 624 ------------------------------------
 625
 626 The function name to use when creating the function directory is "gser".
 627 The SERIAL function provides just one attribute in its function directory:
 628
 629         port_num
 630
 631 The attribute is read-only.
 632
 633 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 634
 635 Testing the SERIAL function
 636 ---------------------------
 637
 638 On host::
 639
 640         insmod usbserial
 641         echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
 642
 643 On host::
 644
 645         cat > /dev/ttyUSB<X>
 646
 647 On target::
 648
 649         cat /dev/ttyGS<Y>
 650
 651 then the other way round
 652
 653 On target::
 654
 655         cat > /dev/ttyGS<Y>
 656
 657 On host::
 658
 659         cat /dev/ttyUSB<X>
 660
 661 15. SOURCESINK function
 662 =======================
 663
 664 The function is provided by usb_f_ss_lb.ko module.
 665
 666 Function-specific configfs interface
 667 ------------------------------------
 668
 669 The function name to use when creating the function directory is "SourceSink".
 670 The SOURCESINK function provides these attributes in its function directory:
 671
 672         =============== ==================================
 673         pattern         0 (all zeros), 1 (mod63), 2 (none)
 674         isoc_interval   1..16
 675         isoc_maxpacket  0 - 1023 (fs), 0 - 1024 (hs/ss)
 676         isoc_mult       0..2 (hs/ss only)
 677         isoc_maxburst   0..15 (ss only)
 678         bulk_buflen     buffer length
 679         bulk_qlen       depth of queue for bulk
 680         iso_qlen        depth of queue for iso
 681         =============== ==================================
 682
 683 Testing the SOURCESINK function
 684 -------------------------------
 685
 686 device: run the gadget
 687
 688 host: test-usb (tools/usb/testusb.c)
 689
 690
 691 16. UAC1 function (legacy implementation)
 692 =========================================
 693
 694 The function is provided by usb_f_uac1_legacy.ko module.
 695
 696 Function-specific configfs interface
 697 ------------------------------------
 698
 699 The function name to use when creating the function directory
 700 is "uac1_legacy".
 701 The uac1 function provides these attributes in its function directory:
 702
 703         =============== ====================================
 704         audio_buf_size  audio buffer size
 705         fn_cap          capture pcm device file name
 706         fn_cntl         control device file name
 707         fn_play         playback pcm device file name
 708         req_buf_size    ISO OUT endpoint request buffer size
 709         req_count       ISO OUT endpoint request count
 710         =============== ====================================
 711
 712 The attributes have sane default values.
 713
 714 Testing the UAC1 function
 715 -------------------------
 716
 717 device: run the gadget
 718
 719 host::
 720
 721         aplay -l # should list our USB Audio Gadget
 722
 723 17. UAC2 function
 724 =================
 725
 726 The function is provided by usb_f_uac2.ko module.
 727
 728 Function-specific configfs interface
 729 ------------------------------------
 730
 731 The function name to use when creating the function directory is "uac2".
 732 The uac2 function provides these attributes in its function directory:
 733
 734         ================ ====================================================
 735         c_chmask         capture channel mask
 736         c_srate          list of capture sampling rates (comma-separated)
 737         c_ssize          capture sample size (bytes)
 738         c_sync           capture synchronization type (async/adaptive)
 739         c_mute_present   capture mute control enable
 740         c_volume_present capture volume control enable
 741         c_volume_min     capture volume control min value (in 1/256 dB)
 742         c_volume_max     capture volume control max value (in 1/256 dB)
 743         c_volume_res     capture volume control resolution (in 1/256 dB)
 744         c_hs_bint        capture bInterval for HS/SS (1-4: fixed, 0: auto)
 745         fb_max           maximum extra bandwidth in async mode
 746         p_chmask         playback channel mask
 747         p_srate          list of playback sampling rates (comma-separated)
 748         p_ssize          playback sample size (bytes)
 749         p_mute_present   playback mute control enable
 750         p_volume_present playback volume control enable
 751         p_volume_min     playback volume control min value (in 1/256 dB)
 752         p_volume_max     playback volume control max value (in 1/256 dB)
 753         p_volume_res     playback volume control resolution (in 1/256 dB)
 754         p_hs_bint        playback bInterval for HS/SS (1-4: fixed, 0: auto)
 755         req_number       the number of pre-allocated request for both capture
 756                          and playback
 757         function_name    name of the interface
 758         c_terminal_type  code of the capture terminal type
 759         p_terminal_type  code of the playback terminal type
 760         ================ ====================================================
 761
 762 The attributes have sane default values.
 763
 764 Testing the UAC2 function
 765 -------------------------
 766
 767 device: run the gadget
 768 host: aplay -l # should list our USB Audio Gadget
 769
 770 This function does not require real hardware support, it just
 771 sends a stream of audio data to/from the host. In order to
 772 actually hear something at the device side, a command similar
 773 to this must be used at the device side::
 774
 775         $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 776
 777 e.g.::
 778
 779         $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
 780           aplay -D default:CARD=OdroidU3
 781
 782 18. UVC function
 783 ================
 784
 785 The function is provided by usb_f_uvc.ko module.
 786
 787 Function-specific configfs interface
 788 ------------------------------------
 789
 790 The function name to use when creating the function directory is "uvc".
 791 The uvc function provides these attributes in its function directory:
 792
 793         =================== ================================================
 794         streaming_interval  interval for polling endpoint for data transfers
 795         streaming_maxburst  bMaxBurst for super speed companion descriptor
 796         streaming_maxpacket maximum packet size this endpoint is capable of
 797                             sending or receiving when this configuration is
 798                             selected
 799         function_name       name of the interface
 800         =================== ================================================
 801
 802 There are also "control" and "streaming" subdirectories, each of which contain
 803 a number of their subdirectories. There are some sane defaults provided, but
 804 the user must provide the following:
 805
 806         ================== ====================================================
 807         control header     create in control/header, link from control/class/fs
 808                            and/or control/class/ss
 809         streaming header   create in streaming/header, link from
 810                            streaming/class/fs and/or streaming/class/hs and/or
 811                            streaming/class/ss
 812         format description create in streaming/mjpeg and/or
 813                            streaming/uncompressed
 814         frame description  create in streaming/mjpeg/<format> and/or in
 815                            streaming/uncompressed/<format>
 816         ================== ====================================================
 817
 818 Each frame description contains frame interval specification, and each
 819 such specification consists of a number of lines with an interval value
 820 in each line. The rules stated above are best illustrated with an example::
 821
 822   # mkdir functions/uvc.usb0/control/header/h
 823   # cd functions/uvc.usb0/control/
 824   # ln -s header/h class/fs
 825   # ln -s header/h class/ss
 826   # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
 827   # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
 828   666666
 829   1000000
 830   5000000
 831   EOF
 832   # cd $GADGET_CONFIGFS_ROOT
 833   # mkdir functions/uvc.usb0/streaming/header/h
 834   # cd functions/uvc.usb0/streaming/header/h
 835   # ln -s ../../uncompressed/u
 836   # cd ../../class/fs
 837   # ln -s ../../header/h
 838   # cd ../../class/hs
 839   # ln -s ../../header/h
 840   # cd ../../class/ss
 841   # ln -s ../../header/h
 842
 843
 844 Testing the UVC function
 845 ------------------------
 846
 847 device: run the gadget, modprobe vivid::
 848
 849   # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
 850
 851 where uvc-gadget is this program:
 852         http://git.ideasonboard.org/uvc-gadget.git
 853
 854 with these patches:
 855
 856         http://www.spinics.net/lists/linux-usb/msg99220.html
 857
 858 host::
 859
 860         luvcview -f yuv
 861
 862 19. PRINTER function
 863 ====================
 864
 865 The function is provided by usb_f_printer.ko module.
 866
 867 Function-specific configfs interface
 868 ------------------------------------
 869
 870 The function name to use when creating the function directory is "printer".
 871 The printer function provides these attributes in its function directory:
 872
 873         ==========      ===========================================
 874         pnp_string      Data to be passed to the host in pnp string
 875         q_len           Number of requests per endpoint
 876         ==========      ===========================================
 877
 878 Testing the PRINTER function
 879 ----------------------------
 880
 881 The most basic testing:
 882
 883 device: run the gadget::
 884
 885         # ls -l /devices/virtual/usb_printer_gadget/
 886
 887 should show g_printer<number>.
 888
 889 If udev is active, then /dev/g_printer<number> should appear automatically.
 890
 891 host:
 892
 893 If udev is active, then e.g. /dev/usb/lp0 should appear.
 894
 895 host->device transmission:
 896
 897 device::
 898
 899         # cat /dev/g_printer<number>
 900
 901 host::
 902
 903         # cat > /dev/usb/lp0
 904
 905 device->host transmission::
 906
 907         # cat > /dev/g_printer<number>
 908
 909 host::
 910
 911         # cat /dev/usb/lp0
 912
 913 More advanced testing can be done with the prn_example
 914 described in Documentation/usb/gadget_printer.rst.
 915
 916
 917 20. UAC1 function (virtual ALSA card, using u_audio API)
 918 ========================================================
 919
 920 The function is provided by usb_f_uac1.ko module.
 921 It will create a virtual ALSA card and the audio streams are simply
 922 sinked to and sourced from it.
 923
 924 Function-specific configfs interface
 925 ------------------------------------
 926
 927 The function name to use when creating the function directory is "uac1".
 928 The uac1 function provides these attributes in its function directory:
 929
 930         ================ ====================================================
 931         c_chmask         capture channel mask
 932         c_srate          list of capture sampling rates (comma-separated)
 933         c_ssize          capture sample size (bytes)
 934         c_mute_present   capture mute control enable
 935         c_volume_present capture volume control enable
 936         c_volume_min     capture volume control min value (in 1/256 dB)
 937         c_volume_max     capture volume control max value (in 1/256 dB)
 938         c_volume_res     capture volume control resolution (in 1/256 dB)
 939         p_chmask         playback channel mask
 940         p_srate          list of playback sampling rates (comma-separated)
 941         p_ssize          playback sample size (bytes)
 942         p_mute_present   playback mute control enable
 943         p_volume_present playback volume control enable
 944         p_volume_min     playback volume control min value (in 1/256 dB)
 945         p_volume_max     playback volume control max value (in 1/256 dB)
 946         p_volume_res     playback volume control resolution (in 1/256 dB)
 947         req_number       the number of pre-allocated requests for both capture
 948                          and playback
 949         function_name    name of the interface
 950         ================ ====================================================
 951
 952 The attributes have sane default values.
 953
 954 Testing the UAC1 function
 955 -------------------------
 956
 957 device: run the gadget
 958 host: aplay -l # should list our USB Audio Gadget
 959
 960 This function does not require real hardware support, it just
 961 sends a stream of audio data to/from the host. In order to
 962 actually hear something at the device side, a command similar
 963 to this must be used at the device side::
 964
 965         $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 966
 967 e.g.::
 968
 969         $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
 970           aplay -D default:CARD=OdroidU3
 971
 972
 973 21. MIDI2 function
 974 ==================
 975
 976 The function is provided by usb_f_midi2.ko module.
 977 It will create a virtual ALSA card containing a UMP rawmidi device
 978 where the UMP packet is looped back. In addition, a legacy rawmidi
 979 device is created. The UMP rawmidi is bound with ALSA sequencer
 980 clients, too.
 981
 982 Function-specific configfs interface
 983 ------------------------------------
 984
 985 The function name to use when creating the function directory is "midi2".
 986 The midi2 function provides these attributes in its function directory
 987 as the card top-level information:
 988
 989         =============   =================================================
 990         process_ump     Bool flag to process UMP Stream messages (0 or 1)
 991         static_block    Bool flag for static blocks (0 or 1)
 992         iface_name      Optional interface name string
 993         =============   =================================================
 994
 995 The directory contains a subdirectory "ep.0", and this provides the
 996 attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):
 997
 998         =============   =================================================
 999         protocol_caps   MIDI protocol capabilities;
1000                         1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
1001         protocol        Default MIDI protocol (either 1 or 2)
1002         ep_name         UMP Endpoint name string
1003         product_id      Product ID string
1004         manufacturer    Manufacture ID number (24 bit)
1005         family          Device family ID number (16 bit)
1006         model           Device model ID number (16 bit)
1007         sw_revision     Software revision (32 bit)
1008         =============   =================================================
1009
1010 Each Endpoint subdirectory contains a subdirectory "block.0", which
1011 represents the Function Block for Block 0 information.
1012 Its attributes are:
1013
1014         =================       ===============================================
1015         name                    Function Block name string
1016         direction               Direction of this FB
1017                                 1: input, 2: output, or 3: bidirectional
1018         first_group             The first UMP Group number (0-15)
1019         num_groups              The number of groups in this FB (1-16)
1020         midi1_first_group       The first UMP Group number for MIDI 1.0 (0-15)
1021         midi1_num_groups        The number of groups for MIDI 1.0 (0-16)
1022         ui_hint                 UI-hint of this FB
1023                                 0: unknown, 1: receiver, 2: sender, 3: both
1024         midi_ci_verison         Supported MIDI-CI version number (8 bit)
1025         is_midi1                Legacy MIDI 1.0 device (0-2)
1026                                 0: MIDI 2.0 device,
1027                                 1: MIDI 1.0 without restriction, or
1028                                 2: MIDI 1.0 with low speed
1029         sysex8_streams          Max number of SysEx8 streams (8 bit)
1030         active                  Bool flag for FB activity (0 or 1)
1031         =================       ===============================================
1032
1033 If multiple Function Blocks are required, you can add more Function
1034 Blocks by creating subdirectories "block.<num>" with the corresponding
1035 Function Block number (1, 2, ....). The FB subdirectories can be
1036 dynamically removed, too. Note that the Function Block numbers must be
1037 continuous.
1038
1039 Similarly, if you multiple UMP Endpoints are required, you can add
1040 more Endpoints by creating subdirectories "ep.<num>". The number must
1041 be continuous.
1042
1043 For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1044 to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1045
1046 Testing the MIDI2 function
1047 --------------------------
1048
1049 On the device: run the gadget, and running::
1050
1051   $ cat /proc/asound/cards
1052
1053 will show a new sound card containing a MIDI2 device.
1054
1055 OTOH, on the host::
1056
1057   $ cat /proc/asound/cards
1058
1059 will show a new sound card containing either MIDI1 or MIDI2 device,
1060 depending on the USB audio driver configuration.
1061
1062 On both, when ALSA sequencer is enabled on the host, you can find the
1063 UMP MIDI client such as "MIDI 2.0 Gadget".
1064
1065 As the driver simply loops back the data, there is no need for a real
1066 device just for testing.
1067
1068 For testing a MIDI input from the gadget to the host (e.g. emulating a
1069 MIDI keyboard), you can send a MIDI stream like the following.
1070
1071 On the gadget::
1072
1073   $ aconnect -o
1074   ....
1075   client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
1076       0 'MIDI 2.0        '
1077       1 'Group 1 (MIDI 2.0 Gadget I/O)'
1078   $ aplaymidi -p 20:1 to_host.mid
1079
1080 On the host::
1081
1082   $ aconnect -i
1083   ....
1084   client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
1085       0 'MIDI 2.0        '
1086       1 'Group 1 (MIDI 2.0 Gadget I/O)'
1087   $ arecordmidi -p 24:1 from_gadget.mid
1088
1089 If you have a UMP-capable application, you can use the UMP port to
1090 send/receive the raw UMP packets, too. For example, aseqdump program
1091 with UMP support can receive from UMP port. On the host::
1092
1093   $ aseqdump -u 2 -p 24:1
1094   Waiting for data. Press Ctrl+C to end.
1095   Source  Group    Event                  Ch  Data
1096    24:1   Group  0, Program change          0, program 0, Bank select 0:0
1097    24:1   Group  0, Channel pressure        0, value 0x80000000
1098
1099 For testing a MIDI output to the gadget to the host (e.g. emulating a
1100 MIDI synth), it'll be just other way round.
1101
1102 On the gadget::
1103
1104   $ arecordmidi -p 20:1 from_host.mid
1105
1106 On the host::
1107
1108   $ aplaymidi -p 24:1 to_gadget.mid
1109
1110 The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1111 translated from/to UMP packets on the gadget. It's bound to only
1112 Function Block 0.
1113
1114 The current operation mode can be observed in ALSA control element
1115 "Operation Mode" for SND_CTL_IFACE_RAWMIDI.  For example::
1116
1117   $ amixer -c1 contents
1118   numid=1,iface=RAWMIDI,name='Operation Mode'
1119     ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
1120     : values=2
1121
1122 where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1123 The example above shows it's running in 2, i.e. MIDI 2.0.