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
31
321. ACM function
33===============
34
35The function is provided by usb_f_acm.ko module.
36
37Function-specific configfs interface
38------------------------------------
39
40The function name to use when creating the function directory is "acm".
41The ACM function provides just one attribute in its function directory:
42
43	port_num
44
45The attribute is read-only.
46
47There can be at most 4 ACM/generic serial/OBEX ports in the system.
48
49
50Testing the ACM function
51------------------------
52
53On the host::
54
55	cat > /dev/ttyACM<X>
56
57On the device::
58
59	cat /dev/ttyGS<Y>
60
61then the other way round
62
63On the device::
64
65	cat > /dev/ttyGS<Y>
66
67On the host::
68
69	cat /dev/ttyACM<X>
70
712. ECM function
72===============
73
74The function is provided by usb_f_ecm.ko module.
75
76Function-specific configfs interface
77------------------------------------
78
79The function name to use when creating the function directory is "ecm".
80The 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
92and after creating the functions/ecm.<instance name> they contain default
93values: qmult is 5, dev_addr and host_addr are randomly selected.
94The ifname can be written to if the function is not bound. A write must be an
95interface pattern such as "usb%d", which will cause the net core to choose the
96next free usbX interface. By default, it is set to "usb%d".
97
98Testing the ECM function
99------------------------
100
101Configure IP addresses of the device and the host. Then:
102
103On the device::
104
105	ping <host's IP>
106
107On the host::
108
109	ping <device's IP>
110
1113. ECM subset function
112======================
113
114The function is provided by usb_f_ecm_subset.ko module.
115
116Function-specific configfs interface
117------------------------------------
118
119The function name to use when creating the function directory is "geth".
120The 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
132and after creating the functions/ecm.<instance name> they contain default
133values: qmult is 5, dev_addr and host_addr are randomly selected.
134The ifname can be written to if the function is not bound. A write must be an
135interface pattern such as "usb%d", which will cause the net core to choose the
136next free usbX interface. By default, it is set to "usb%d".
137
138Testing the ECM subset function
139-------------------------------
140
141Configure IP addresses of the device and the host. Then:
142
143On the device::
144
145	ping <host's IP>
146
147On the host::
148
149	ping <device's IP>
150
1514. EEM function
152===============
153
154The function is provided by usb_f_eem.ko module.
155
156Function-specific configfs interface
157------------------------------------
158
159The function name to use when creating the function directory is "eem".
160The 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
172and after creating the functions/eem.<instance name> they contain default
173values: qmult is 5, dev_addr and host_addr are randomly selected.
174The ifname can be written to if the function is not bound. A write must be an
175interface pattern such as "usb%d", which will cause the net core to choose the
176next free usbX interface. By default, it is set to "usb%d".
177
178Testing the EEM function
179------------------------
180
181Configure IP addresses of the device and the host. Then:
182
183On the device::
184
185	ping <host's IP>
186
187On the host::
188
189	ping <device's IP>
190
1915. FFS function
192===============
193
194The function is provided by usb_f_fs.ko module.
195
196Function-specific configfs interface
197------------------------------------
198
199The function name to use when creating the function directory is "ffs".
200The function directory is intentionally empty and not modifiable.
201
202After creating the directory there is a new instance (a "device") of FunctionFS
203available in the system. Once a "device" is available, the user should follow
204the standard procedure for using FunctionFS (mount it, run the userspace
205process which implements the function proper). The gadget should be enabled
206by writing a suitable string to usb_gadget/<gadget>/UDC.
207
208Testing the FFS function
209------------------------
210
211On the device: start the function's userspace daemon, enable the gadget
212
213On the host: use the USB function provided by the device
214
2156. HID function
216===============
217
218The function is provided by usb_f_hid.ko module.
219
220Function-specific configfs interface
221------------------------------------
222
223The function name to use when creating the function directory is "hid".
224The 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
234For a keyboard the protocol and the subclass are 1, the report_length is 8,
235while 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
244Such a sequence of bytes can be stored to the attribute with echo::
245
246  $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
247
248Testing the HID function
249------------------------
250
251Device:
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
261Host:
262
263- observe the keystrokes from the gadget
264
2657. LOOPBACK function
266====================
267
268The function is provided by usb_f_ss_lb.ko module.
269
270Function-specific configfs interface
271------------------------------------
272
273The function name to use when creating the function directory is "Loopback".
274The LOOPBACK function provides these attributes in its function directory:
275
276	=============== =======================
277	qlen		depth of loopback queue
278	bulk_buflen	buffer length
279	=============== =======================
280
281Testing the LOOPBACK function
282-----------------------------
283
284device: run the gadget
285
286host: test-usb (tools/usb/testusb.c)
287
2888. MASS STORAGE function
289========================
290
291The function is provided by usb_f_mass_storage.ko module.
292
293Function-specific configfs interface
294------------------------------------
295
296The function name to use when creating the function directory is "mass_storage".
297The MASS STORAGE function provides these attributes in its directory:
298files:
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
309and a default lun.0 directory corresponding to SCSI LUN #0.
310
311A new lun can be added with mkdir::
312
313	$ mkdir functions/mass_storage.0/partition.5
314
315Lun numbering does not have to be continuous, except for lun #0 which is
316created by default. A maximum of 8 luns can be specified and they all must be
317named following the <name>.<number> scheme. The numbers can be 0..8.
318Probably a good convention is to name the luns "lun.<number>",
319although it is not mandatory.
320
321In 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
338Testing the MASS STORAGE function
339---------------------------------
340
341device: connect the gadget, enable it
342host: dmesg, see the USB drives appear (if system configured to automatically
343mount)
344
3459. MIDI function
346================
347
348The function is provided by usb_f_midi.ko module.
349
350Function-specific configfs interface
351------------------------------------
352
353The function name to use when creating the function directory is "midi".
354The 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
365Testing the MIDI function
366-------------------------
367
368There are two cases: playing a mid from the gadget to
369the host and playing a mid from the host to the gadget.
370
3711) Playing a mid from the gadget to the host:
372
373host::
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
381gadget::
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
3892) Playing a mid from the host to the gadget
390
391gadget::
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
399host::
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
408The from_gadget.mid should sound identical to the to_host.mid.
409
410The from_host.id should sound identical to the to_gadget.mid.
411
412MIDI 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
425MIDI ports can be logically connected using the aconnect utility, e.g.::
426
427  $ aconnect 24:0 128:0 # try it on the host
428
429After the gadget's MIDI port is connected to timidity's MIDI port,
430whatever is played at the gadget side with aplaymidi -l is audible
431in host's speakers/headphones.
432
43310. NCM function
434================
435
436The function is provided by usb_f_ncm.ko module.
437
438Function-specific configfs interface
439------------------------------------
440
441The function name to use when creating the function directory is "ncm".
442The 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
454and after creating the functions/ncm.<instance name> they contain default
455values: qmult is 5, dev_addr and host_addr are randomly selected.
456The ifname can be written to if the function is not bound. A write must be an
457interface pattern such as "usb%d", which will cause the net core to choose the
458next free usbX interface. By default, it is set to "usb%d".
459
460Testing the NCM function
461------------------------
462
463Configure IP addresses of the device and the host. Then:
464
465On the device::
466
467	ping <host's IP>
468
469On the host::
470
471	ping <device's IP>
472
47311. OBEX function
474=================
475
476The function is provided by usb_f_obex.ko module.
477
478Function-specific configfs interface
479------------------------------------
480
481The function name to use when creating the function directory is "obex".
482The OBEX function provides just one attribute in its function directory:
483
484	port_num
485
486The attribute is read-only.
487
488There can be at most 4 ACM/generic serial/OBEX ports in the system.
489
490Testing the OBEX function
491-------------------------
492
493On device::
494
495	seriald -f /dev/ttyGS<Y> -s 1024
496
497On host::
498
499	serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
500                -t<out endpoint addr> -r<in endpoint addr>
501
502where seriald and serialc are Felipe's utilities found here:
503
504	https://github.com/felipebalbi/usb-tools.git master
505
50612. PHONET function
507===================
508
509The function is provided by usb_f_phonet.ko module.
510
511Function-specific configfs interface
512------------------------------------
513
514The function name to use when creating the function directory is "phonet".
515The 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
522Testing the PHONET function
523---------------------------
524
525It is not possible to test the SOCK_STREAM protocol without a specific piece
526of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
527in the past I had to apply the patch mentioned here:
528
529http://www.spinics.net/lists/linux-usb/msg85689.html
530
531These tools are required:
532
533git://git.gitorious.org/meego-cellular/phonet-utils.git
534
535On the host::
536
537	$ ./phonet -a 0x10 -i usbpn0
538	$ ./pnroute add 0x6c usbpn0
539	$./pnroute add 0x10 usbpn0
540	$ ifconfig usbpn0 up
541
542On the device::
543
544	$ ./phonet -a 0x6c -i upnlink0
545	$ ./pnroute add 0x10 upnlink0
546	$ ifconfig upnlink0 up
547
548Then a test program can be used::
549
550	http://www.spinics.net/lists/linux-usb/msg85690.html
551
552On the device::
553
554	$ ./pnxmit -a 0x6c -r
555
556On the host::
557
558	$ ./pnxmit -a 0x10 -s 0x6c
559
560As a result some data should be sent from host to device.
561Then the other way round:
562
563On the host::
564
565	$ ./pnxmit -a 0x10 -r
566
567On the device::
568
569	$ ./pnxmit -a 0x6c -s 0x10
570
57113. RNDIS function
572==================
573
574The function is provided by usb_f_rndis.ko module.
575
576Function-specific configfs interface
577------------------------------------
578
579The function name to use when creating the function directory is "rndis".
580The 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
592and after creating the functions/rndis.<instance name> they contain default
593values: qmult is 5, dev_addr and host_addr are randomly selected.
594The ifname can be written to if the function is not bound. A write must be an
595interface pattern such as "usb%d", which will cause the net core to choose the
596next free usbX interface. By default, it is set to "usb%d".
597
598Testing the RNDIS function
599--------------------------
600
601Configure IP addresses of the device and the host. Then:
602
603On the device::
604
605	ping <host's IP>
606
607On the host::
608
609	ping <device's IP>
610
61114. SERIAL function
612===================
613
614The function is provided by usb_f_gser.ko module.
615
616Function-specific configfs interface
617------------------------------------
618
619The function name to use when creating the function directory is "gser".
620The SERIAL function provides just one attribute in its function directory:
621
622	port_num
623
624The attribute is read-only.
625
626There can be at most 4 ACM/generic serial/OBEX ports in the system.
627
628Testing the SERIAL function
629---------------------------
630
631On host::
632
633	insmod usbserial
634	echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
635
636On host::
637
638	cat > /dev/ttyUSB<X>
639
640On target::
641
642	cat /dev/ttyGS<Y>
643
644then the other way round
645
646On target::
647
648	cat > /dev/ttyGS<Y>
649
650On host::
651
652	cat /dev/ttyUSB<X>
653
65415. SOURCESINK function
655=======================
656
657The function is provided by usb_f_ss_lb.ko module.
658
659Function-specific configfs interface
660------------------------------------
661
662The function name to use when creating the function directory is "SourceSink".
663The 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
676Testing the SOURCESINK function
677-------------------------------
678
679device: run the gadget
680
681host: test-usb (tools/usb/testusb.c)
682
683
68416. UAC1 function (legacy implementation)
685=========================================
686
687The function is provided by usb_f_uac1_legacy.ko module.
688
689Function-specific configfs interface
690------------------------------------
691
692The function name to use when creating the function directory
693is "uac1_legacy".
694The 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
705The attributes have sane default values.
706
707Testing the UAC1 function
708-------------------------
709
710device: run the gadget
711
712host::
713
714	aplay -l # should list our USB Audio Gadget
715
71617. UAC2 function
717=================
718
719The function is provided by usb_f_uac2.ko module.
720
721Function-specific configfs interface
722------------------------------------
723
724The function name to use when creating the function directory is "uac2".
725The 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
753The attributes have sane default values.
754
755Testing the UAC2 function
756-------------------------
757
758device: run the gadget
759host: aplay -l # should list our USB Audio Gadget
760
761This function does not require real hardware support, it just
762sends a stream of audio data to/from the host. In order to
763actually hear something at the device side, a command similar
764to 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
768e.g.::
769
770	$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
771	  aplay -D default:CARD=OdroidU3
772
77318. UVC function
774================
775
776The function is provided by usb_f_uvc.ko module.
777
778Function-specific configfs interface
779------------------------------------
780
781The function name to use when creating the function directory is "uvc".
782The 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
792There are also "control" and "streaming" subdirectories, each of which contain
793a number of their subdirectories. There are some sane defaults provided, but
794the 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
808Each frame description contains frame interval specification, and each
809such specification consists of a number of lines with an inverval value
810in 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
834Testing the UVC function
835------------------------
836
837device: run the gadget, modprobe vivid::
838
839  # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
840
841where uvc-gadget is this program:
842	http://git.ideasonboard.org/uvc-gadget.git
843
844with these patches:
845
846	http://www.spinics.net/lists/linux-usb/msg99220.html
847
848host::
849
850	luvcview -f yuv
851
85219. PRINTER function
853====================
854
855The function is provided by usb_f_printer.ko module.
856
857Function-specific configfs interface
858------------------------------------
859
860The function name to use when creating the function directory is "printer".
861The 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
868Testing the PRINTER function
869----------------------------
870
871The most basic testing:
872
873device: run the gadget::
874
875	# ls -l /devices/virtual/usb_printer_gadget/
876
877should show g_printer<number>.
878
879If udev is active, then /dev/g_printer<number> should appear automatically.
880
881host:
882
883If udev is active, then e.g. /dev/usb/lp0 should appear.
884
885host->device transmission:
886
887device::
888
889	# cat /dev/g_printer<number>
890
891host::
892
893	# cat > /dev/usb/lp0
894
895device->host transmission::
896
897	# cat > /dev/g_printer<number>
898
899host::
900
901	# cat /dev/usb/lp0
902
903More advanced testing can be done with the prn_example
904described in Documentation/usb/gadget_printer.rst.
905
906
90720. UAC1 function (virtual ALSA card, using u_audio API)
908========================================================
909
910The function is provided by usb_f_uac1.ko module.
911It will create a virtual ALSA card and the audio streams are simply
912sinked to and sourced from it.
913
914Function-specific configfs interface
915------------------------------------
916
917The function name to use when creating the function directory is "uac1".
918The 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
942The attributes have sane default values.
943
944Testing the UAC1 function
945-------------------------
946
947device: run the gadget
948host: aplay -l # should list our USB Audio Gadget
949
950This function does not require real hardware support, it just
951sends a stream of audio data to/from the host. In order to
952actually hear something at the device side, a command similar
953to 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
957e.g.::
958
959	$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
960	  aplay -D default:CARD=OdroidU3
961