1==============
2Gadget Testing
3==============
4
5This file summarizes information on basic testing of USB functions
6provided 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
331. ACM function
34===============
35
36The function is provided by usb_f_acm.ko module.
37
38Function-specific configfs interface
39------------------------------------
40
41The function name to use when creating the function directory is "acm".
42The ACM function provides just one attribute in its function directory:
43
44	port_num
45
46The attribute is read-only.
47
48There can be at most 4 ACM/generic serial/OBEX ports in the system.
49
50
51Testing the ACM function
52------------------------
53
54On the host::
55
56	cat > /dev/ttyACM<X>
57
58On the device::
59
60	cat /dev/ttyGS<Y>
61
62then the other way round
63
64On the device::
65
66	cat > /dev/ttyGS<Y>
67
68On the host::
69
70	cat /dev/ttyACM<X>
71
722. ECM function
73===============
74
75The function is provided by usb_f_ecm.ko module.
76
77Function-specific configfs interface
78------------------------------------
79
80The function name to use when creating the function directory is "ecm".
81The 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
93and after creating the functions/ecm.<instance name> they contain default
94values: qmult is 5, dev_addr and host_addr are randomly selected.
95The ifname can be written to if the function is not bound. A write must be an
96interface pattern such as "usb%d", which will cause the net core to choose the
97next free usbX interface. By default, it is set to "usb%d".
98
99Testing the ECM function
100------------------------
101
102Configure IP addresses of the device and the host. Then:
103
104On the device::
105
106	ping <host's IP>
107
108On the host::
109
110	ping <device's IP>
111
1123. ECM subset function
113======================
114
115The function is provided by usb_f_ecm_subset.ko module.
116
117Function-specific configfs interface
118------------------------------------
119
120The function name to use when creating the function directory is "geth".
121The 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
133and after creating the functions/ecm.<instance name> they contain default
134values: qmult is 5, dev_addr and host_addr are randomly selected.
135The ifname can be written to if the function is not bound. A write must be an
136interface pattern such as "usb%d", which will cause the net core to choose the
137next free usbX interface. By default, it is set to "usb%d".
138
139Testing the ECM subset function
140-------------------------------
141
142Configure IP addresses of the device and the host. Then:
143
144On the device::
145
146	ping <host's IP>
147
148On the host::
149
150	ping <device's IP>
151
1524. EEM function
153===============
154
155The function is provided by usb_f_eem.ko module.
156
157Function-specific configfs interface
158------------------------------------
159
160The function name to use when creating the function directory is "eem".
161The 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
173and after creating the functions/eem.<instance name> they contain default
174values: qmult is 5, dev_addr and host_addr are randomly selected.
175The ifname can be written to if the function is not bound. A write must be an
176interface pattern such as "usb%d", which will cause the net core to choose the
177next free usbX interface. By default, it is set to "usb%d".
178
179Testing the EEM function
180------------------------
181
182Configure IP addresses of the device and the host. Then:
183
184On the device::
185
186	ping <host's IP>
187
188On the host::
189
190	ping <device's IP>
191
1925. FFS function
193===============
194
195The function is provided by usb_f_fs.ko module.
196
197Function-specific configfs interface
198------------------------------------
199
200The function name to use when creating the function directory is "ffs".
201The function directory is intentionally empty and not modifiable.
202
203After creating the directory there is a new instance (a "device") of FunctionFS
204available in the system. Once a "device" is available, the user should follow
205the standard procedure for using FunctionFS (mount it, run the userspace
206process which implements the function proper). The gadget should be enabled
207by writing a suitable string to usb_gadget/<gadget>/UDC.
208
209Testing the FFS function
210------------------------
211
212On the device: start the function's userspace daemon, enable the gadget
213
214On the host: use the USB function provided by the device
215
2166. HID function
217===============
218
219The function is provided by usb_f_hid.ko module.
220
221Function-specific configfs interface
222------------------------------------
223
224The function name to use when creating the function directory is "hid".
225The 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
235For a keyboard the protocol and the subclass are 1, the report_length is 8,
236while 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
245Such a sequence of bytes can be stored to the attribute with echo::
246
247  $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
248
249Testing the HID function
250------------------------
251
252Device:
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
262Host:
263
264- observe the keystrokes from the gadget
265
2667. LOOPBACK function
267====================
268
269The function is provided by usb_f_ss_lb.ko module.
270
271Function-specific configfs interface
272------------------------------------
273
274The function name to use when creating the function directory is "Loopback".
275The LOOPBACK function provides these attributes in its function directory:
276
277	=============== =======================
278	qlen		depth of loopback queue
279	bulk_buflen	buffer length
280	=============== =======================
281
282Testing the LOOPBACK function
283-----------------------------
284
285device: run the gadget
286
287host: test-usb (tools/usb/testusb.c)
288
2898. MASS STORAGE function
290========================
291
292The function is provided by usb_f_mass_storage.ko module.
293
294Function-specific configfs interface
295------------------------------------
296
297The function name to use when creating the function directory is "mass_storage".
298The MASS STORAGE function provides these attributes in its directory:
299files:
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
310and a default lun.0 directory corresponding to SCSI LUN #0.
311
312A new lun can be added with mkdir::
313
314	$ mkdir functions/mass_storage.0/partition.5
315
316Lun numbering does not have to be continuous, except for lun #0 which is
317created by default. A maximum of 8 luns can be specified and they all must be
318named following the <name>.<number> scheme. The numbers can be 0..8.
319Probably a good convention is to name the luns "lun.<number>",
320although it is not mandatory.
321
322In 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
345Testing the MASS STORAGE function
346---------------------------------
347
348device: connect the gadget, enable it
349host: dmesg, see the USB drives appear (if system configured to automatically
350mount)
351
3529. MIDI function
353================
354
355The function is provided by usb_f_midi.ko module.
356
357Function-specific configfs interface
358------------------------------------
359
360The function name to use when creating the function directory is "midi".
361The 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
372Testing the MIDI function
373-------------------------
374
375There are two cases: playing a mid from the gadget to
376the host and playing a mid from the host to the gadget.
377
3781) Playing a mid from the gadget to the host:
379
380host::
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
388gadget::
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
3962) Playing a mid from the host to the gadget
397
398gadget::
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
406host::
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
415The from_gadget.mid should sound identical to the to_host.mid.
416
417The from_host.id should sound identical to the to_gadget.mid.
418
419MIDI 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
432MIDI ports can be logically connected using the aconnect utility, e.g.::
433
434  $ aconnect 24:0 128:0 # try it on the host
435
436After the gadget's MIDI port is connected to timidity's MIDI port,
437whatever is played at the gadget side with aplaymidi -l is audible
438in host's speakers/headphones.
439
44010. NCM function
441================
442
443The function is provided by usb_f_ncm.ko module.
444
445Function-specific configfs interface
446------------------------------------
447
448The function name to use when creating the function directory is "ncm".
449The 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
461and after creating the functions/ncm.<instance name> they contain default
462values: qmult is 5, dev_addr and host_addr are randomly selected.
463The ifname can be written to if the function is not bound. A write must be an
464interface pattern such as "usb%d", which will cause the net core to choose the
465next free usbX interface. By default, it is set to "usb%d".
466
467Testing the NCM function
468------------------------
469
470Configure IP addresses of the device and the host. Then:
471
472On the device::
473
474	ping <host's IP>
475
476On the host::
477
478	ping <device's IP>
479
48011. OBEX function
481=================
482
483The function is provided by usb_f_obex.ko module.
484
485Function-specific configfs interface
486------------------------------------
487
488The function name to use when creating the function directory is "obex".
489The OBEX function provides just one attribute in its function directory:
490
491	port_num
492
493The attribute is read-only.
494
495There can be at most 4 ACM/generic serial/OBEX ports in the system.
496
497Testing the OBEX function
498-------------------------
499
500On device::
501
502	seriald -f /dev/ttyGS<Y> -s 1024
503
504On host::
505
506	serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
507                -t<out endpoint addr> -r<in endpoint addr>
508
509where seriald and serialc are Felipe's utilities found here:
510
511	https://github.com/felipebalbi/usb-tools.git master
512
51312. PHONET function
514===================
515
516The function is provided by usb_f_phonet.ko module.
517
518Function-specific configfs interface
519------------------------------------
520
521The function name to use when creating the function directory is "phonet".
522The 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
529Testing the PHONET function
530---------------------------
531
532It is not possible to test the SOCK_STREAM protocol without a specific piece
533of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
534in the past I had to apply the patch mentioned here:
535
536http://www.spinics.net/lists/linux-usb/msg85689.html
537
538These tools are required:
539
540git://git.gitorious.org/meego-cellular/phonet-utils.git
541
542On the host::
543
544	$ ./phonet -a 0x10 -i usbpn0
545	$ ./pnroute add 0x6c usbpn0
546	$./pnroute add 0x10 usbpn0
547	$ ifconfig usbpn0 up
548
549On the device::
550
551	$ ./phonet -a 0x6c -i upnlink0
552	$ ./pnroute add 0x10 upnlink0
553	$ ifconfig upnlink0 up
554
555Then a test program can be used::
556
557	http://www.spinics.net/lists/linux-usb/msg85690.html
558
559On the device::
560
561	$ ./pnxmit -a 0x6c -r
562
563On the host::
564
565	$ ./pnxmit -a 0x10 -s 0x6c
566
567As a result some data should be sent from host to device.
568Then the other way round:
569
570On the host::
571
572	$ ./pnxmit -a 0x10 -r
573
574On the device::
575
576	$ ./pnxmit -a 0x6c -s 0x10
577
57813. RNDIS function
579==================
580
581The function is provided by usb_f_rndis.ko module.
582
583Function-specific configfs interface
584------------------------------------
585
586The function name to use when creating the function directory is "rndis".
587The 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
599and after creating the functions/rndis.<instance name> they contain default
600values: qmult is 5, dev_addr and host_addr are randomly selected.
601The ifname can be written to if the function is not bound. A write must be an
602interface pattern such as "usb%d", which will cause the net core to choose the
603next free usbX interface. By default, it is set to "usb%d".
604
605Testing the RNDIS function
606--------------------------
607
608Configure IP addresses of the device and the host. Then:
609
610On the device::
611
612	ping <host's IP>
613
614On the host::
615
616	ping <device's IP>
617
61814. SERIAL function
619===================
620
621The function is provided by usb_f_gser.ko module.
622
623Function-specific configfs interface
624------------------------------------
625
626The function name to use when creating the function directory is "gser".
627The SERIAL function provides just one attribute in its function directory:
628
629	port_num
630
631The attribute is read-only.
632
633There can be at most 4 ACM/generic serial/OBEX ports in the system.
634
635Testing the SERIAL function
636---------------------------
637
638On host::
639
640	insmod usbserial
641	echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
642
643On host::
644
645	cat > /dev/ttyUSB<X>
646
647On target::
648
649	cat /dev/ttyGS<Y>
650
651then the other way round
652
653On target::
654
655	cat > /dev/ttyGS<Y>
656
657On host::
658
659	cat /dev/ttyUSB<X>
660
66115. SOURCESINK function
662=======================
663
664The function is provided by usb_f_ss_lb.ko module.
665
666Function-specific configfs interface
667------------------------------------
668
669The function name to use when creating the function directory is "SourceSink".
670The 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
683Testing the SOURCESINK function
684-------------------------------
685
686device: run the gadget
687
688host: test-usb (tools/usb/testusb.c)
689
690
69116. UAC1 function (legacy implementation)
692=========================================
693
694The function is provided by usb_f_uac1_legacy.ko module.
695
696Function-specific configfs interface
697------------------------------------
698
699The function name to use when creating the function directory
700is "uac1_legacy".
701The 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
712The attributes have sane default values.
713
714Testing the UAC1 function
715-------------------------
716
717device: run the gadget
718
719host::
720
721	aplay -l # should list our USB Audio Gadget
722
72317. UAC2 function
724=================
725
726The function is provided by usb_f_uac2.ko module.
727
728Function-specific configfs interface
729------------------------------------
730
731The function name to use when creating the function directory is "uac2".
732The 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
760The attributes have sane default values.
761
762Testing the UAC2 function
763-------------------------
764
765device: run the gadget
766host: aplay -l # should list our USB Audio Gadget
767
768This function does not require real hardware support, it just
769sends a stream of audio data to/from the host. In order to
770actually hear something at the device side, a command similar
771to 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
775e.g.::
776
777	$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
778	  aplay -D default:CARD=OdroidU3
779
78018. UVC function
781================
782
783The function is provided by usb_f_uvc.ko module.
784
785Function-specific configfs interface
786------------------------------------
787
788The function name to use when creating the function directory is "uvc".
789The 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
800There are also "control" and "streaming" subdirectories, each of which contain
801a number of their subdirectories. There are some sane defaults provided, but
802the 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
816Each frame description contains frame interval specification, and each
817such specification consists of a number of lines with an interval value
818in 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
842Testing the UVC function
843------------------------
844
845device: run the gadget, modprobe vivid::
846
847  # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
848
849where uvc-gadget is this program:
850	http://git.ideasonboard.org/uvc-gadget.git
851
852with these patches:
853
854	http://www.spinics.net/lists/linux-usb/msg99220.html
855
856host::
857
858	luvcview -f yuv
859
86019. PRINTER function
861====================
862
863The function is provided by usb_f_printer.ko module.
864
865Function-specific configfs interface
866------------------------------------
867
868The function name to use when creating the function directory is "printer".
869The 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
876Testing the PRINTER function
877----------------------------
878
879The most basic testing:
880
881device: run the gadget::
882
883	# ls -l /devices/virtual/usb_printer_gadget/
884
885should show g_printer<number>.
886
887If udev is active, then /dev/g_printer<number> should appear automatically.
888
889host:
890
891If udev is active, then e.g. /dev/usb/lp0 should appear.
892
893host->device transmission:
894
895device::
896
897	# cat /dev/g_printer<number>
898
899host::
900
901	# cat > /dev/usb/lp0
902
903device->host transmission::
904
905	# cat > /dev/g_printer<number>
906
907host::
908
909	# cat /dev/usb/lp0
910
911More advanced testing can be done with the prn_example
912described in Documentation/usb/gadget_printer.rst.
913
914
91520. UAC1 function (virtual ALSA card, using u_audio API)
916========================================================
917
918The function is provided by usb_f_uac1.ko module.
919It will create a virtual ALSA card and the audio streams are simply
920sinked to and sourced from it.
921
922Function-specific configfs interface
923------------------------------------
924
925The function name to use when creating the function directory is "uac1".
926The 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
950The attributes have sane default values.
951
952Testing the UAC1 function
953-------------------------
954
955device: run the gadget
956host: aplay -l # should list our USB Audio Gadget
957
958This function does not require real hardware support, it just
959sends a stream of audio data to/from the host. In order to
960actually hear something at the device side, a command similar
961to 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
965e.g.::
966
967	$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
968	  aplay -D default:CARD=OdroidU3
969
970
97121. MIDI2 function
972==================
973
974The function is provided by usb_f_midi2.ko module.
975It will create a virtual ALSA card containing a UMP rawmidi device
976where the UMP packet is looped back. In addition, a legacy rawmidi
977device is created. The UMP rawmidi is bound with ALSA sequencer
978clients, too.
979
980Function-specific configfs interface
981------------------------------------
982
983The function name to use when creating the function directory is "midi2".
984The midi2 function provides these attributes in its function directory
985as 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
993The directory contains a subdirectory "ep.0", and this provides the
994attributes 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
1008Each Endpoint subdirectory contains a subdirectory "block.0", which
1009represents the Function Block for Block 0 information.
1010Its 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
1031If multiple Function Blocks are required, you can add more Function
1032Blocks by creating subdirectories "block.<num>" with the corresponding
1033Function Block number (1, 2, ....). The FB subdirectories can be
1034dynamically removed, too. Note that the Function Block numbers must be
1035continuous.
1036
1037Similarly, if you multiple UMP Endpoints are required, you can add
1038more Endpoints by creating subdirectories "ep.<num>". The number must
1039be continuous.
1040
1041For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1042to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1043
1044Testing the MIDI2 function
1045--------------------------
1046
1047On the device: run the gadget, and running::
1048
1049  $ cat /proc/asound/cards
1050
1051will show a new sound card containing a MIDI2 device.
1052
1053OTOH, on the host::
1054
1055  $ cat /proc/asound/cards
1056
1057will show a new sound card containing either MIDI1 or MIDI2 device,
1058depending on the USB audio driver configuration.
1059
1060On both, when ALSA sequencer is enabled on the host, you can find the
1061UMP MIDI client such as "MIDI 2.0 Gadget".
1062
1063As the driver simply loops back the data, there is no need for a real
1064device just for testing.
1065
1066For testing a MIDI input from the gadget to the host (e.g. emulating a
1067MIDI keyboard), you can send a MIDI stream like the following.
1068
1069On 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
1078On 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
1087If you have a UMP-capable application, you can use the UMP port to
1088send/receive the raw UMP packets, too. For example, aseqdump program
1089with 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
1097For testing a MIDI output to the gadget to the host (e.g. emulating a
1098MIDI synth), it'll be just other way round.
1099
1100On the gadget::
1101
1102  $ arecordmidi -p 20:1 from_host.mid
1103
1104On the host::
1105
1106  $ aplaymidi -p 24:1 to_gadget.mid
1107
1108The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1109translated from/to UMP packets on the gadget. It's bound to only
1110Function Block 0.
1111
1112The 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
1120where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1121The example above shows it's running in 2, i.e. MIDI 2.0.
1122