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