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