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         max_segment_size        Segment size required for P2P connections. This
 460                                 will set MTU to 14 bytes
 461         ======================= ==================================================
 462
 463 and after creating the functions/ncm.<instance name> they contain default
 464 values: qmult is 5, dev_addr and host_addr are randomly selected.
 465 The ifname can be written to if the function is not bound. A write must be an
 466 interface pattern such as "usb%d", which will cause the net core to choose the
 467 next free usbX interface. By default, it is set to "usb%d".
 468
 469 Testing the NCM function
 470 ------------------------
 471
 472 Configure IP addresses of the device and the host. Then:
 473
 474 On the device::
 475
 476         ping <host's IP>
 477
 478 On the host::
 479
 480         ping <device's IP>
 481
 482 11. OBEX function
 483 =================
 484
 485 The function is provided by usb_f_obex.ko module.
 486
 487 Function-specific configfs interface
 488 ------------------------------------
 489
 490 The function name to use when creating the function directory is "obex".
 491 The OBEX function provides just one attribute in its function directory:
 492
 493         port_num
 494
 495 The attribute is read-only.
 496
 497 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 498
 499 Testing the OBEX function
 500 -------------------------
 501
 502 On device::
 503
 504         seriald -f /dev/ttyGS<Y> -s 1024
 505
 506 On host::
 507
 508         serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
 509                 -t<out endpoint addr> -r<in endpoint addr>
 510
 511 where seriald and serialc are Felipe's utilities found here:
 512
 513         https://github.com/felipebalbi/usb-tools.git master
 514
 515 12. PHONET function
 516 ===================
 517
 518 The function is provided by usb_f_phonet.ko module.
 519
 520 Function-specific configfs interface
 521 ------------------------------------
 522
 523 The function name to use when creating the function directory is "phonet".
 524 The PHONET function provides just one attribute in its function directory:
 525
 526         =============== ==================================================
 527         ifname          network device interface name associated with this
 528                         function instance
 529         =============== ==================================================
 530
 531 Testing the PHONET function
 532 ---------------------------
 533
 534 It is not possible to test the SOCK_STREAM protocol without a specific piece
 535 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
 536 in the past I had to apply the patch mentioned here:
 537
 538 http://www.spinics.net/lists/linux-usb/msg85689.html
 539
 540 These tools are required:
 541
 542 git://git.gitorious.org/meego-cellular/phonet-utils.git
 543
 544 On the host::
 545
 546         $ ./phonet -a 0x10 -i usbpn0
 547         $ ./pnroute add 0x6c usbpn0
 548         $./pnroute add 0x10 usbpn0
 549         $ ifconfig usbpn0 up
 550
 551 On the device::
 552
 553         $ ./phonet -a 0x6c -i upnlink0
 554         $ ./pnroute add 0x10 upnlink0
 555         $ ifconfig upnlink0 up
 556
 557 Then a test program can be used::
 558
 559         http://www.spinics.net/lists/linux-usb/msg85690.html
 560
 561 On the device::
 562
 563         $ ./pnxmit -a 0x6c -r
 564
 565 On the host::
 566
 567         $ ./pnxmit -a 0x10 -s 0x6c
 568
 569 As a result some data should be sent from host to device.
 570 Then the other way round:
 571
 572 On the host::
 573
 574         $ ./pnxmit -a 0x10 -r
 575
 576 On the device::
 577
 578         $ ./pnxmit -a 0x6c -s 0x10
 579
 580 13. RNDIS function
 581 ==================
 582
 583 The function is provided by usb_f_rndis.ko module.
 584
 585 Function-specific configfs interface
 586 ------------------------------------
 587
 588 The function name to use when creating the function directory is "rndis".
 589 The RNDIS function provides these attributes in its function directory:
 590
 591         =============== ==================================================
 592         ifname          network device interface name associated with this
 593                         function instance
 594         qmult           queue length multiplier for high and super speed
 595         host_addr       MAC address of host's end of this
 596                         Ethernet over USB link
 597         dev_addr        MAC address of device's end of this
 598                         Ethernet over USB link
 599         =============== ==================================================
 600
 601 and after creating the functions/rndis.<instance name> they contain default
 602 values: qmult is 5, dev_addr and host_addr are randomly selected.
 603 The ifname can be written to if the function is not bound. A write must be an
 604 interface pattern such as "usb%d", which will cause the net core to choose the
 605 next free usbX interface. By default, it is set to "usb%d".
 606
 607 Testing the RNDIS function
 608 --------------------------
 609
 610 Configure IP addresses of the device and the host. Then:
 611
 612 On the device::
 613
 614         ping <host's IP>
 615
 616 On the host::
 617
 618         ping <device's IP>
 619
 620 14. SERIAL function
 621 ===================
 622
 623 The function is provided by usb_f_gser.ko module.
 624
 625 Function-specific configfs interface
 626 ------------------------------------
 627
 628 The function name to use when creating the function directory is "gser".
 629 The SERIAL function provides just one attribute in its function directory:
 630
 631         port_num
 632
 633 The attribute is read-only.
 634
 635 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 636
 637 Testing the SERIAL function
 638 ---------------------------
 639
 640 On host::
 641
 642         insmod usbserial
 643         echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
 644
 645 On host::
 646
 647         cat > /dev/ttyUSB<X>
 648
 649 On target::
 650
 651         cat /dev/ttyGS<Y>
 652
 653 then the other way round
 654
 655 On target::
 656
 657         cat > /dev/ttyGS<Y>
 658
 659 On host::
 660
 661         cat /dev/ttyUSB<X>
 662
 663 15. SOURCESINK function
 664 =======================
 665
 666 The function is provided by usb_f_ss_lb.ko module.
 667
 668 Function-specific configfs interface
 669 ------------------------------------
 670
 671 The function name to use when creating the function directory is "SourceSink".
 672 The SOURCESINK function provides these attributes in its function directory:
 673
 674         =============== ==================================
 675         pattern         0 (all zeros), 1 (mod63), 2 (none)
 676         isoc_interval   1..16
 677         isoc_maxpacket  0 - 1023 (fs), 0 - 1024 (hs/ss)
 678         isoc_mult       0..2 (hs/ss only)
 679         isoc_maxburst   0..15 (ss only)
 680         bulk_buflen     buffer length
 681         bulk_qlen       depth of queue for bulk
 682         iso_qlen        depth of queue for iso
 683         =============== ==================================
 684
 685 Testing the SOURCESINK function
 686 -------------------------------
 687
 688 device: run the gadget
 689
 690 host: test-usb (tools/usb/testusb.c)
 691
 692
 693 16. UAC1 function (legacy implementation)
 694 =========================================
 695
 696 The function is provided by usb_f_uac1_legacy.ko module.
 697
 698 Function-specific configfs interface
 699 ------------------------------------
 700
 701 The function name to use when creating the function directory
 702 is "uac1_legacy".
 703 The uac1 function provides these attributes in its function directory:
 704
 705         =============== ====================================
 706         audio_buf_size  audio buffer size
 707         fn_cap          capture pcm device file name
 708         fn_cntl         control device file name
 709         fn_play         playback pcm device file name
 710         req_buf_size    ISO OUT endpoint request buffer size
 711         req_count       ISO OUT endpoint request count
 712         =============== ====================================
 713
 714 The attributes have sane default values.
 715
 716 Testing the UAC1 function
 717 -------------------------
 718
 719 device: run the gadget
 720
 721 host::
 722
 723         aplay -l # should list our USB Audio Gadget
 724
 725 17. UAC2 function
 726 =================
 727
 728 The function is provided by usb_f_uac2.ko module.
 729
 730 Function-specific configfs interface
 731 ------------------------------------
 732
 733 The function name to use when creating the function directory is "uac2".
 734 The uac2 function provides these attributes in its function directory:
 735
 736         ================ ====================================================
 737         c_chmask         capture channel mask
 738         c_srate          list of capture sampling rates (comma-separated)
 739         c_ssize          capture sample size (bytes)
 740         c_sync           capture synchronization type (async/adaptive)
 741         c_mute_present   capture mute control enable
 742         c_volume_present capture volume control enable
 743         c_volume_min     capture volume control min value (in 1/256 dB)
 744         c_volume_max     capture volume control max value (in 1/256 dB)
 745         c_volume_res     capture volume control resolution (in 1/256 dB)
 746         c_hs_bint        capture bInterval for HS/SS (1-4: fixed, 0: auto)
 747         fb_max           maximum extra bandwidth in async mode
 748         p_chmask         playback channel mask
 749         p_srate          list of playback sampling rates (comma-separated)
 750         p_ssize          playback sample size (bytes)
 751         p_mute_present   playback mute control enable
 752         p_volume_present playback volume control enable
 753         p_volume_min     playback volume control min value (in 1/256 dB)
 754         p_volume_max     playback volume control max value (in 1/256 dB)
 755         p_volume_res     playback volume control resolution (in 1/256 dB)
 756         p_hs_bint        playback bInterval for HS/SS (1-4: fixed, 0: auto)
 757         req_number       the number of pre-allocated request for both capture
 758                          and playback
 759         function_name    name of the interface
 760         c_terminal_type  code of the capture terminal type
 761         p_terminal_type  code of the playback terminal type
 762         ================ ====================================================
 763
 764 The attributes have sane default values.
 765
 766 Testing the UAC2 function
 767 -------------------------
 768
 769 device: run the gadget
 770 host: aplay -l # should list our USB Audio Gadget
 771
 772 This function does not require real hardware support, it just
 773 sends a stream of audio data to/from the host. In order to
 774 actually hear something at the device side, a command similar
 775 to this must be used at the device side::
 776
 777         $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 778
 779 e.g.::
 780
 781         $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
 782           aplay -D default:CARD=OdroidU3
 783
 784 18. UVC function
 785 ================
 786
 787 The function is provided by usb_f_uvc.ko module.
 788
 789 Function-specific configfs interface
 790 ------------------------------------
 791
 792 The function name to use when creating the function directory is "uvc".
 793 The uvc function provides these attributes in its function directory:
 794
 795         =================== ================================================
 796         streaming_interval  interval for polling endpoint for data transfers
 797         streaming_maxburst  bMaxBurst for super speed companion descriptor
 798         streaming_maxpacket maximum packet size this endpoint is capable of
 799                             sending or receiving when this configuration is
 800                             selected
 801         function_name       name of the interface
 802         =================== ================================================
 803
 804 There are also "control" and "streaming" subdirectories, each of which contain
 805 a number of their subdirectories. There are some sane defaults provided, but
 806 the user must provide the following:
 807
 808         ================== ====================================================
 809         control header     create in control/header, link from control/class/fs
 810                            and/or control/class/ss
 811         streaming header   create in streaming/header, link from
 812                            streaming/class/fs and/or streaming/class/hs and/or
 813                            streaming/class/ss
 814         format description create in streaming/mjpeg and/or
 815                            streaming/uncompressed
 816         frame description  create in streaming/mjpeg/<format> and/or in
 817                            streaming/uncompressed/<format>
 818         ================== ====================================================
 819
 820 Each frame description contains frame interval specification, and each
 821 such specification consists of a number of lines with an interval value
 822 in each line. The rules stated above are best illustrated with an example::
 823
 824   # mkdir functions/uvc.usb0/control/header/h
 825   # cd functions/uvc.usb0/control/
 826   # ln -s header/h class/fs
 827   # ln -s header/h class/ss
 828   # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
 829   # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
 830   666666
 831   1000000
 832   5000000
 833   EOF
 834   # cd $GADGET_CONFIGFS_ROOT
 835   # mkdir functions/uvc.usb0/streaming/header/h
 836   # cd functions/uvc.usb0/streaming/header/h
 837   # ln -s ../../uncompressed/u
 838   # cd ../../class/fs
 839   # ln -s ../../header/h
 840   # cd ../../class/hs
 841   # ln -s ../../header/h
 842   # cd ../../class/ss
 843   # ln -s ../../header/h
 844
 845
 846 Testing the UVC function
 847 ------------------------
 848
 849 device: run the gadget, modprobe vivid::
 850
 851   # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
 852
 853 where uvc-gadget is this program:
 854         http://git.ideasonboard.org/uvc-gadget.git
 855
 856 with these patches:
 857
 858         http://www.spinics.net/lists/linux-usb/msg99220.html
 859
 860 host::
 861
 862         luvcview -f yuv
 863
 864 19. PRINTER function
 865 ====================
 866
 867 The function is provided by usb_f_printer.ko module.
 868
 869 Function-specific configfs interface
 870 ------------------------------------
 871
 872 The function name to use when creating the function directory is "printer".
 873 The printer function provides these attributes in its function directory:
 874
 875         ==========      ===========================================
 876         pnp_string      Data to be passed to the host in pnp string
 877         q_len           Number of requests per endpoint
 878         ==========      ===========================================
 879
 880 Testing the PRINTER function
 881 ----------------------------
 882
 883 The most basic testing:
 884
 885 device: run the gadget::
 886
 887         # ls -l /devices/virtual/usb_printer_gadget/
 888
 889 should show g_printer<number>.
 890
 891 If udev is active, then /dev/g_printer<number> should appear automatically.
 892
 893 host:
 894
 895 If udev is active, then e.g. /dev/usb/lp0 should appear.
 896
 897 host->device transmission:
 898
 899 device::
 900
 901         # cat /dev/g_printer<number>
 902
 903 host::
 904
 905         # cat > /dev/usb/lp0
 906
 907 device->host transmission::
 908
 909         # cat > /dev/g_printer<number>
 910
 911 host::
 912
 913         # cat /dev/usb/lp0
 914
 915 More advanced testing can be done with the prn_example
 916 described in Documentation/usb/gadget_printer.rst.
 917
 918
 919 20. UAC1 function (virtual ALSA card, using u_audio API)
 920 ========================================================
 921
 922 The function is provided by usb_f_uac1.ko module.
 923 It will create a virtual ALSA card and the audio streams are simply
 924 sinked to and sourced from it.
 925
 926 Function-specific configfs interface
 927 ------------------------------------
 928
 929 The function name to use when creating the function directory is "uac1".
 930 The uac1 function provides these attributes in its function directory:
 931
 932         ================ ====================================================
 933         c_chmask         capture channel mask
 934         c_srate          list of capture sampling rates (comma-separated)
 935         c_ssize          capture sample size (bytes)
 936         c_mute_present   capture mute control enable
 937         c_volume_present capture volume control enable
 938         c_volume_min     capture volume control min value (in 1/256 dB)
 939         c_volume_max     capture volume control max value (in 1/256 dB)
 940         c_volume_res     capture volume control resolution (in 1/256 dB)
 941         p_chmask         playback channel mask
 942         p_srate          list of playback sampling rates (comma-separated)
 943         p_ssize          playback sample size (bytes)
 944         p_mute_present   playback mute control enable
 945         p_volume_present playback volume control enable
 946         p_volume_min     playback volume control min value (in 1/256 dB)
 947         p_volume_max     playback volume control max value (in 1/256 dB)
 948         p_volume_res     playback volume control resolution (in 1/256 dB)
 949         req_number       the number of pre-allocated requests for both capture
 950                          and playback
 951         function_name    name of the interface
 952         ================ ====================================================
 953
 954 The attributes have sane default values.
 955
 956 Testing the UAC1 function
 957 -------------------------
 958
 959 device: run the gadget
 960 host: aplay -l # should list our USB Audio Gadget
 961
 962 This function does not require real hardware support, it just
 963 sends a stream of audio data to/from the host. In order to
 964 actually hear something at the device side, a command similar
 965 to this must be used at the device side::
 966
 967         $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 968
 969 e.g.::
 970
 971         $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
 972           aplay -D default:CARD=OdroidU3
 973
 974
 975 21. MIDI2 function
 976 ==================
 977
 978 The function is provided by usb_f_midi2.ko module.
 979 It will create a virtual ALSA card containing a UMP rawmidi device
 980 where the UMP packet is looped back. In addition, a legacy rawmidi
 981 device is created. The UMP rawmidi is bound with ALSA sequencer
 982 clients, too.
 983
 984 Function-specific configfs interface
 985 ------------------------------------
 986
 987 The function name to use when creating the function directory is "midi2".
 988 The midi2 function provides these attributes in its function directory
 989 as the card top-level information:
 990
 991         =============   =================================================
 992         process_ump     Bool flag to process UMP Stream messages (0 or 1)
 993         static_block    Bool flag for static blocks (0 or 1)
 994         iface_name      Optional interface name string
 995         =============   =================================================
 996
 997 The directory contains a subdirectory "ep.0", and this provides the
 998 attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):
 999
1000         =============   =================================================
1001         protocol_caps   MIDI protocol capabilities;
1002                         1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
1003         protocol        Default MIDI protocol (either 1 or 2)
1004         ep_name         UMP Endpoint name string
1005         product_id      Product ID string
1006         manufacturer    Manufacture ID number (24 bit)
1007         family          Device family ID number (16 bit)
1008         model           Device model ID number (16 bit)
1009         sw_revision     Software revision (32 bit)
1010         =============   =================================================
1011
1012 Each Endpoint subdirectory contains a subdirectory "block.0", which
1013 represents the Function Block for Block 0 information.
1014 Its attributes are:
1015
1016         =================       ===============================================
1017         name                    Function Block name string
1018         direction               Direction of this FB
1019                                 1: input, 2: output, or 3: bidirectional
1020         first_group             The first UMP Group number (0-15)
1021         num_groups              The number of groups in this FB (1-16)
1022         midi1_first_group       The first UMP Group number for MIDI 1.0 (0-15)
1023         midi1_num_groups        The number of groups for MIDI 1.0 (0-16)
1024         ui_hint                 UI-hint of this FB
1025                                 0: unknown, 1: receiver, 2: sender, 3: both
1026         midi_ci_verison         Supported MIDI-CI version number (8 bit)
1027         is_midi1                Legacy MIDI 1.0 device (0-2)
1028                                 0: MIDI 2.0 device,
1029                                 1: MIDI 1.0 without restriction, or
1030                                 2: MIDI 1.0 with low speed
1031         sysex8_streams          Max number of SysEx8 streams (8 bit)
1032         active                  Bool flag for FB activity (0 or 1)
1033         =================       ===============================================
1034
1035 If multiple Function Blocks are required, you can add more Function
1036 Blocks by creating subdirectories "block.<num>" with the corresponding
1037 Function Block number (1, 2, ....). The FB subdirectories can be
1038 dynamically removed, too. Note that the Function Block numbers must be
1039 continuous.
1040
1041 Similarly, if you multiple UMP Endpoints are required, you can add
1042 more Endpoints by creating subdirectories "ep.<num>". The number must
1043 be continuous.
1044
1045 For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1046 to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1047
1048 Testing the MIDI2 function
1049 --------------------------
1050
1051 On the device: run the gadget, and running::
1052
1053   $ cat /proc/asound/cards
1054
1055 will show a new sound card containing a MIDI2 device.
1056
1057 OTOH, on the host::
1058
1059   $ cat /proc/asound/cards
1060
1061 will show a new sound card containing either MIDI1 or MIDI2 device,
1062 depending on the USB audio driver configuration.
1063
1064 On both, when ALSA sequencer is enabled on the host, you can find the
1065 UMP MIDI client such as "MIDI 2.0 Gadget".
1066
1067 As the driver simply loops back the data, there is no need for a real
1068 device just for testing.
1069
1070 For testing a MIDI input from the gadget to the host (e.g. emulating a
1071 MIDI keyboard), you can send a MIDI stream like the following.
1072
1073 On the gadget::
1074
1075   $ aconnect -o
1076   ....
1077   client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
1078       0 'MIDI 2.0        '
1079       1 'Group 1 (MIDI 2.0 Gadget I/O)'
1080   $ aplaymidi -p 20:1 to_host.mid
1081
1082 On the host::
1083
1084   $ aconnect -i
1085   ....
1086   client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
1087       0 'MIDI 2.0        '
1088       1 'Group 1 (MIDI 2.0 Gadget I/O)'
1089   $ arecordmidi -p 24:1 from_gadget.mid
1090
1091 If you have a UMP-capable application, you can use the UMP port to
1092 send/receive the raw UMP packets, too. For example, aseqdump program
1093 with UMP support can receive from UMP port. On the host::
1094
1095   $ aseqdump -u 2 -p 24:1
1096   Waiting for data. Press Ctrl+C to end.
1097   Source  Group    Event                  Ch  Data
1098    24:1   Group  0, Program change          0, program 0, Bank select 0:0
1099    24:1   Group  0, Channel pressure        0, value 0x80000000
1100
1101 For testing a MIDI output to the gadget to the host (e.g. emulating a
1102 MIDI synth), it'll be just other way round.
1103
1104 On the gadget::
1105
1106   $ arecordmidi -p 20:1 from_host.mid
1107
1108 On the host::
1109
1110   $ aplaymidi -p 24:1 to_gadget.mid
1111
1112 The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1113 translated from/to UMP packets on the gadget. It's bound to only
1114 Function Block 0.
1115
1116 The current operation mode can be observed in ALSA control element
1117 "Operation Mode" for SND_CTL_IFACE_RAWMIDI.  For example::
1118
1119   $ amixer -c1 contents
1120   numid=1,iface=RAWMIDI,name='Operation Mode'
1121     ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
1122     : values=2
1123
1124 where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1125 The example above shows it's running in 2, i.e. MIDI 2.0.