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         =============== ==============================================
 337
 338 Testing the MASS STORAGE function
 339 ---------------------------------
 340
 341 device: connect the gadget, enable it
 342 host: dmesg, see the USB drives appear (if system configured to automatically
 343 mount)
 344
 345 9. MIDI function
 346 ================
 347
 348 The function is provided by usb_f_midi.ko module.
 349
 350 Function-specific configfs interface
 351 ------------------------------------
 352
 353 The function name to use when creating the function directory is "midi".
 354 The MIDI function provides these attributes in its function directory:
 355
 356         =============== ====================================
 357         buflen          MIDI buffer length
 358         id              ID string for the USB MIDI adapter
 359         in_ports        number of MIDI input ports
 360         index           index value for the USB MIDI adapter
 361         out_ports       number of MIDI output ports
 362         qlen            USB read request queue length
 363         =============== ====================================
 364
 365 Testing the MIDI function
 366 -------------------------
 367
 368 There are two cases: playing a mid from the gadget to
 369 the host and playing a mid from the host to the gadget.
 370
 371 1) Playing a mid from the gadget to the host:
 372
 373 host::
 374
 375   $ arecordmidi -l
 376    Port    Client name                      Port name
 377    14:0    Midi Through                     Midi Through Port-0
 378    24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 379   $ arecordmidi -p 24:0 from_gadget.mid
 380
 381 gadget::
 382
 383   $ aplaymidi -l
 384    Port    Client name                      Port name
 385    20:0    f_midi                           f_midi
 386
 387   $ aplaymidi -p 20:0 to_host.mid
 388
 389 2) Playing a mid from the host to the gadget
 390
 391 gadget::
 392
 393   $ arecordmidi -l
 394    Port    Client name                      Port name
 395    20:0    f_midi                           f_midi
 396
 397   $ arecordmidi -p 20:0 from_host.mid
 398
 399 host::
 400
 401   $ aplaymidi -l
 402    Port    Client name                      Port name
 403    14:0    Midi Through                     Midi Through Port-0
 404    24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 405
 406   $ aplaymidi -p24:0 to_gadget.mid
 407
 408 The from_gadget.mid should sound identical to the to_host.mid.
 409
 410 The from_host.id should sound identical to the to_gadget.mid.
 411
 412 MIDI files can be played to speakers/headphones with e.g. timidity installed::
 413
 414   $ aplaymidi -l
 415    Port    Client name                      Port name
 416    14:0    Midi Through                     Midi Through Port-0
 417    24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 418   128:0    TiMidity                         TiMidity port 0
 419   128:1    TiMidity                         TiMidity port 1
 420   128:2    TiMidity                         TiMidity port 2
 421   128:3    TiMidity                         TiMidity port 3
 422
 423   $ aplaymidi -p 128:0 file.mid
 424
 425 MIDI ports can be logically connected using the aconnect utility, e.g.::
 426
 427   $ aconnect 24:0 128:0 # try it on the host
 428
 429 After the gadget's MIDI port is connected to timidity's MIDI port,
 430 whatever is played at the gadget side with aplaymidi -l is audible
 431 in host's speakers/headphones.
 432
 433 10. NCM function
 434 ================
 435
 436 The function is provided by usb_f_ncm.ko module.
 437
 438 Function-specific configfs interface
 439 ------------------------------------
 440
 441 The function name to use when creating the function directory is "ncm".
 442 The NCM function provides these attributes in its function directory:
 443
 444         =============== ==================================================
 445         ifname          network device interface name associated with this
 446                         function instance
 447         qmult           queue length multiplier for high and super speed
 448         host_addr       MAC address of host's end of this
 449                         Ethernet over USB link
 450         dev_addr        MAC address of device's end of this
 451                         Ethernet over USB link
 452         =============== ==================================================
 453
 454 and after creating the functions/ncm.<instance name> they contain default
 455 values: qmult is 5, dev_addr and host_addr are randomly selected.
 456 The ifname can be written to if the function is not bound. A write must be an
 457 interface pattern such as "usb%d", which will cause the net core to choose the
 458 next free usbX interface. By default, it is set to "usb%d".
 459
 460 Testing the NCM function
 461 ------------------------
 462
 463 Configure IP addresses of the device and the host. Then:
 464
 465 On the device::
 466
 467         ping <host's IP>
 468
 469 On the host::
 470
 471         ping <device's IP>
 472
 473 11. OBEX function
 474 =================
 475
 476 The function is provided by usb_f_obex.ko module.
 477
 478 Function-specific configfs interface
 479 ------------------------------------
 480
 481 The function name to use when creating the function directory is "obex".
 482 The OBEX function provides just one attribute in its function directory:
 483
 484         port_num
 485
 486 The attribute is read-only.
 487
 488 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 489
 490 Testing the OBEX function
 491 -------------------------
 492
 493 On device::
 494
 495         seriald -f /dev/ttyGS<Y> -s 1024
 496
 497 On host::
 498
 499         serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
 500                 -t<out endpoint addr> -r<in endpoint addr>
 501
 502 where seriald and serialc are Felipe's utilities found here:
 503
 504         https://github.com/felipebalbi/usb-tools.git master
 505
 506 12. PHONET function
 507 ===================
 508
 509 The function is provided by usb_f_phonet.ko module.
 510
 511 Function-specific configfs interface
 512 ------------------------------------
 513
 514 The function name to use when creating the function directory is "phonet".
 515 The PHONET function provides just one attribute in its function directory:
 516
 517         =============== ==================================================
 518         ifname          network device interface name associated with this
 519                         function instance
 520         =============== ==================================================
 521
 522 Testing the PHONET function
 523 ---------------------------
 524
 525 It is not possible to test the SOCK_STREAM protocol without a specific piece
 526 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
 527 in the past I had to apply the patch mentioned here:
 528
 529 http://www.spinics.net/lists/linux-usb/msg85689.html
 530
 531 These tools are required:
 532
 533 git://git.gitorious.org/meego-cellular/phonet-utils.git
 534
 535 On the host::
 536
 537         $ ./phonet -a 0x10 -i usbpn0
 538         $ ./pnroute add 0x6c usbpn0
 539         $./pnroute add 0x10 usbpn0
 540         $ ifconfig usbpn0 up
 541
 542 On the device::
 543
 544         $ ./phonet -a 0x6c -i upnlink0
 545         $ ./pnroute add 0x10 upnlink0
 546         $ ifconfig upnlink0 up
 547
 548 Then a test program can be used::
 549
 550         http://www.spinics.net/lists/linux-usb/msg85690.html
 551
 552 On the device::
 553
 554         $ ./pnxmit -a 0x6c -r
 555
 556 On the host::
 557
 558         $ ./pnxmit -a 0x10 -s 0x6c
 559
 560 As a result some data should be sent from host to device.
 561 Then the other way round:
 562
 563 On the host::
 564
 565         $ ./pnxmit -a 0x10 -r
 566
 567 On the device::
 568
 569         $ ./pnxmit -a 0x6c -s 0x10
 570
 571 13. RNDIS function
 572 ==================
 573
 574 The function is provided by usb_f_rndis.ko module.
 575
 576 Function-specific configfs interface
 577 ------------------------------------
 578
 579 The function name to use when creating the function directory is "rndis".
 580 The RNDIS function provides these attributes in its function directory:
 581
 582         =============== ==================================================
 583         ifname          network device interface name associated with this
 584                         function instance
 585         qmult           queue length multiplier for high and super speed
 586         host_addr       MAC address of host's end of this
 587                         Ethernet over USB link
 588         dev_addr        MAC address of device's end of this
 589                         Ethernet over USB link
 590         =============== ==================================================
 591
 592 and after creating the functions/rndis.<instance name> they contain default
 593 values: qmult is 5, dev_addr and host_addr are randomly selected.
 594 The ifname can be written to if the function is not bound. A write must be an
 595 interface pattern such as "usb%d", which will cause the net core to choose the
 596 next free usbX interface. By default, it is set to "usb%d".
 597
 598 Testing the RNDIS function
 599 --------------------------
 600
 601 Configure IP addresses of the device and the host. Then:
 602
 603 On the device::
 604
 605         ping <host's IP>
 606
 607 On the host::
 608
 609         ping <device's IP>
 610
 611 14. SERIAL function
 612 ===================
 613
 614 The function is provided by usb_f_gser.ko module.
 615
 616 Function-specific configfs interface
 617 ------------------------------------
 618
 619 The function name to use when creating the function directory is "gser".
 620 The SERIAL function provides just one attribute in its function directory:
 621
 622         port_num
 623
 624 The attribute is read-only.
 625
 626 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 627
 628 Testing the SERIAL function
 629 ---------------------------
 630
 631 On host::
 632
 633         insmod usbserial
 634         echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
 635
 636 On host::
 637
 638         cat > /dev/ttyUSB<X>
 639
 640 On target::
 641
 642         cat /dev/ttyGS<Y>
 643
 644 then the other way round
 645
 646 On target::
 647
 648         cat > /dev/ttyGS<Y>
 649
 650 On host::
 651
 652         cat /dev/ttyUSB<X>
 653
 654 15. SOURCESINK function
 655 =======================
 656
 657 The function is provided by usb_f_ss_lb.ko module.
 658
 659 Function-specific configfs interface
 660 ------------------------------------
 661
 662 The function name to use when creating the function directory is "SourceSink".
 663 The SOURCESINK function provides these attributes in its function directory:
 664
 665         =============== ==================================
 666         pattern         0 (all zeros), 1 (mod63), 2 (none)
 667         isoc_interval   1..16
 668         isoc_maxpacket  0 - 1023 (fs), 0 - 1024 (hs/ss)
 669         isoc_mult       0..2 (hs/ss only)
 670         isoc_maxburst   0..15 (ss only)
 671         bulk_buflen     buffer length
 672         bulk_qlen       depth of queue for bulk
 673         iso_qlen        depth of queue for iso
 674         =============== ==================================
 675
 676 Testing the SOURCESINK function
 677 -------------------------------
 678
 679 device: run the gadget
 680
 681 host: test-usb (tools/usb/testusb.c)
 682
 683
 684 16. UAC1 function (legacy implementation)
 685 =========================================
 686
 687 The function is provided by usb_f_uac1_legacy.ko module.
 688
 689 Function-specific configfs interface
 690 ------------------------------------
 691
 692 The function name to use when creating the function directory
 693 is "uac1_legacy".
 694 The uac1 function provides these attributes in its function directory:
 695
 696         =============== ====================================
 697         audio_buf_size  audio buffer size
 698         fn_cap          capture pcm device file name
 699         fn_cntl         control device file name
 700         fn_play         playback pcm device file name
 701         req_buf_size    ISO OUT endpoint request buffer size
 702         req_count       ISO OUT endpoint request count
 703         =============== ====================================
 704
 705 The attributes have sane default values.
 706
 707 Testing the UAC1 function
 708 -------------------------
 709
 710 device: run the gadget
 711
 712 host::
 713
 714         aplay -l # should list our USB Audio Gadget
 715
 716 17. UAC2 function
 717 =================
 718
 719 The function is provided by usb_f_uac2.ko module.
 720
 721 Function-specific configfs interface
 722 ------------------------------------
 723
 724 The function name to use when creating the function directory is "uac2".
 725 The uac2 function provides these attributes in its function directory:
 726
 727         ================ ====================================================
 728         c_chmask         capture channel mask
 729         c_srate          list of capture sampling rates (comma-separated)
 730         c_ssize          capture sample size (bytes)
 731         c_sync           capture synchronization type (async/adaptive)
 732         c_mute_present   capture mute control enable
 733         c_volume_present capture volume control enable
 734         c_volume_min     capture volume control min value (in 1/256 dB)
 735         c_volume_max     capture volume control max value (in 1/256 dB)
 736         c_volume_res     capture volume control resolution (in 1/256 dB)
 737         c_hs_bint        capture bInterval for HS/SS (1-4: fixed, 0: auto)
 738         fb_max           maximum extra bandwidth in async mode
 739         p_chmask         playback channel mask
 740         p_srate          list of playback sampling rates (comma-separated)
 741         p_ssize          playback sample size (bytes)
 742         p_mute_present   playback mute control enable
 743         p_volume_present playback volume control enable
 744         p_volume_min     playback volume control min value (in 1/256 dB)
 745         p_volume_max     playback volume control max value (in 1/256 dB)
 746         p_volume_res     playback volume control resolution (in 1/256 dB)
 747         p_hs_bint        playback bInterval for HS/SS (1-4: fixed, 0: auto)
 748         req_number       the number of pre-allocated request for both capture
 749                          and playback
 750         function_name    name of the interface
 751         ================ ====================================================
 752
 753 The attributes have sane default values.
 754
 755 Testing the UAC2 function
 756 -------------------------
 757
 758 device: run the gadget
 759 host: aplay -l # should list our USB Audio Gadget
 760
 761 This function does not require real hardware support, it just
 762 sends a stream of audio data to/from the host. In order to
 763 actually hear something at the device side, a command similar
 764 to this must be used at the device side::
 765
 766         $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 767
 768 e.g.::
 769
 770         $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
 771           aplay -D default:CARD=OdroidU3
 772
 773 18. UVC function
 774 ================
 775
 776 The function is provided by usb_f_uvc.ko module.
 777
 778 Function-specific configfs interface
 779 ------------------------------------
 780
 781 The function name to use when creating the function directory is "uvc".
 782 The uvc function provides these attributes in its function directory:
 783
 784         =================== ================================================
 785         streaming_interval  interval for polling endpoint for data transfers
 786         streaming_maxburst  bMaxBurst for super speed companion descriptor
 787         streaming_maxpacket maximum packet size this endpoint is capable of
 788                             sending or receiving when this configuration is
 789                             selected
 790         =================== ================================================
 791
 792 There are also "control" and "streaming" subdirectories, each of which contain
 793 a number of their subdirectories. There are some sane defaults provided, but
 794 the user must provide the following:
 795
 796         ================== ====================================================
 797         control header     create in control/header, link from control/class/fs
 798                            and/or control/class/ss
 799         streaming header   create in streaming/header, link from
 800                            streaming/class/fs and/or streaming/class/hs and/or
 801                            streaming/class/ss
 802         format description create in streaming/mjpeg and/or
 803                            streaming/uncompressed
 804         frame description  create in streaming/mjpeg/<format> and/or in
 805                            streaming/uncompressed/<format>
 806         ================== ====================================================
 807
 808 Each frame description contains frame interval specification, and each
 809 such specification consists of a number of lines with an inverval value
 810 in each line. The rules stated above are best illustrated with an example::
 811
 812   # mkdir functions/uvc.usb0/control/header/h
 813   # cd functions/uvc.usb0/control/
 814   # ln -s header/h class/fs
 815   # ln -s header/h class/ss
 816   # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
 817   # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
 818   666666
 819   1000000
 820   5000000
 821   EOF
 822   # cd $GADGET_CONFIGFS_ROOT
 823   # mkdir functions/uvc.usb0/streaming/header/h
 824   # cd functions/uvc.usb0/streaming/header/h
 825   # ln -s ../../uncompressed/u
 826   # cd ../../class/fs
 827   # ln -s ../../header/h
 828   # cd ../../class/hs
 829   # ln -s ../../header/h
 830   # cd ../../class/ss
 831   # ln -s ../../header/h
 832
 833
 834 Testing the UVC function
 835 ------------------------
 836
 837 device: run the gadget, modprobe vivid::
 838
 839   # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
 840
 841 where uvc-gadget is this program:
 842         http://git.ideasonboard.org/uvc-gadget.git
 843
 844 with these patches:
 845
 846         http://www.spinics.net/lists/linux-usb/msg99220.html
 847
 848 host::
 849
 850         luvcview -f yuv
 851
 852 19. PRINTER function
 853 ====================
 854
 855 The function is provided by usb_f_printer.ko module.
 856
 857 Function-specific configfs interface
 858 ------------------------------------
 859
 860 The function name to use when creating the function directory is "printer".
 861 The printer function provides these attributes in its function directory:
 862
 863         ==========      ===========================================
 864         pnp_string      Data to be passed to the host in pnp string
 865         q_len           Number of requests per endpoint
 866         ==========      ===========================================
 867
 868 Testing the PRINTER function
 869 ----------------------------
 870
 871 The most basic testing:
 872
 873 device: run the gadget::
 874
 875         # ls -l /devices/virtual/usb_printer_gadget/
 876
 877 should show g_printer<number>.
 878
 879 If udev is active, then /dev/g_printer<number> should appear automatically.
 880
 881 host:
 882
 883 If udev is active, then e.g. /dev/usb/lp0 should appear.
 884
 885 host->device transmission:
 886
 887 device::
 888
 889         # cat /dev/g_printer<number>
 890
 891 host::
 892
 893         # cat > /dev/usb/lp0
 894
 895 device->host transmission::
 896
 897         # cat > /dev/g_printer<number>
 898
 899 host::
 900
 901         # cat /dev/usb/lp0
 902
 903 More advanced testing can be done with the prn_example
 904 described in Documentation/usb/gadget_printer.rst.
 905
 906
 907 20. UAC1 function (virtual ALSA card, using u_audio API)
 908 ========================================================
 909
 910 The function is provided by usb_f_uac1.ko module.
 911 It will create a virtual ALSA card and the audio streams are simply
 912 sinked to and sourced from it.
 913
 914 Function-specific configfs interface
 915 ------------------------------------
 916
 917 The function name to use when creating the function directory is "uac1".
 918 The uac1 function provides these attributes in its function directory:
 919
 920         ================ ====================================================
 921         c_chmask         capture channel mask
 922         c_srate          list of capture sampling rates (comma-separated)
 923         c_ssize          capture sample size (bytes)
 924         c_mute_present   capture mute control enable
 925         c_volume_present capture volume control enable
 926         c_volume_min     capture volume control min value (in 1/256 dB)
 927         c_volume_max     capture volume control max value (in 1/256 dB)
 928         c_volume_res     capture volume control resolution (in 1/256 dB)
 929         p_chmask         playback channel mask
 930         p_srate          list of playback sampling rates (comma-separated)
 931         p_ssize          playback sample size (bytes)
 932         p_mute_present   playback mute control enable
 933         p_volume_present playback volume control enable
 934         p_volume_min     playback volume control min value (in 1/256 dB)
 935         p_volume_max     playback volume control max value (in 1/256 dB)
 936         p_volume_res     playback volume control resolution (in 1/256 dB)
 937         req_number       the number of pre-allocated requests for both capture
 938                          and playback
 939         function_name    name of the interface
 940         ================ ====================================================
 941
 942 The attributes have sane default values.
 943
 944 Testing the UAC1 function
 945 -------------------------
 946
 947 device: run the gadget
 948 host: aplay -l # should list our USB Audio Gadget
 949
 950 This function does not require real hardware support, it just
 951 sends a stream of audio data to/from the host. In order to
 952 actually hear something at the device side, a command similar
 953 to this must be used at the device side::
 954
 955         $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 956
 957 e.g.::
 958
 959         $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
 960           aplay -D default:CARD=OdroidU3