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