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          capture sampling rate
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	fb_max           maximum extra bandwidth in async mode
738	p_chmask         playback channel mask
739	p_srate          playback sampling rate
740	p_ssize          playback sample size (bytes)
741	p_mute_present   playback mute control enable
742	p_volume_present playback volume control enable
743	p_volume_min     playback volume control min value (in 1/256 dB)
744	p_volume_max     playback volume control max value (in 1/256 dB)
745	p_volume_res     playback volume control resolution (in 1/256 dB)
746	req_number       the number of pre-allocated request for both capture
747	                 and playback
748	================ ====================================================
749
750The attributes have sane default values.
751
752Testing the UAC2 function
753-------------------------
754
755device: run the gadget
756host: aplay -l # should list our USB Audio Gadget
757
758This function does not require real hardware support, it just
759sends a stream of audio data to/from the host. In order to
760actually hear something at the device side, a command similar
761to this must be used at the device side::
762
763	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
764
765e.g.::
766
767	$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
768	  aplay -D default:CARD=OdroidU3
769
77018. UVC function
771================
772
773The function is provided by usb_f_uvc.ko module.
774
775Function-specific configfs interface
776------------------------------------
777
778The function name to use when creating the function directory is "uvc".
779The uvc function provides these attributes in its function directory:
780
781	=================== ================================================
782	streaming_interval  interval for polling endpoint for data transfers
783	streaming_maxburst  bMaxBurst for super speed companion descriptor
784	streaming_maxpacket maximum packet size this endpoint is capable of
785			    sending or receiving when this configuration is
786			    selected
787	=================== ================================================
788
789There are also "control" and "streaming" subdirectories, each of which contain
790a number of their subdirectories. There are some sane defaults provided, but
791the user must provide the following:
792
793	================== ====================================================
794	control header     create in control/header, link from control/class/fs
795			   and/or control/class/ss
796	streaming header   create in streaming/header, link from
797			   streaming/class/fs and/or streaming/class/hs and/or
798			   streaming/class/ss
799	format description create in streaming/mjpeg and/or
800			   streaming/uncompressed
801	frame description  create in streaming/mjpeg/<format> and/or in
802			   streaming/uncompressed/<format>
803	================== ====================================================
804
805Each frame description contains frame interval specification, and each
806such specification consists of a number of lines with an inverval value
807in each line. The rules stated above are best illustrated with an example::
808
809  # mkdir functions/uvc.usb0/control/header/h
810  # cd functions/uvc.usb0/control/
811  # ln -s header/h class/fs
812  # ln -s header/h class/ss
813  # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
814  # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
815  666666
816  1000000
817  5000000
818  EOF
819  # cd $GADGET_CONFIGFS_ROOT
820  # mkdir functions/uvc.usb0/streaming/header/h
821  # cd functions/uvc.usb0/streaming/header/h
822  # ln -s ../../uncompressed/u
823  # cd ../../class/fs
824  # ln -s ../../header/h
825  # cd ../../class/hs
826  # ln -s ../../header/h
827  # cd ../../class/ss
828  # ln -s ../../header/h
829
830
831Testing the UVC function
832------------------------
833
834device: run the gadget, modprobe vivid::
835
836  # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
837
838where uvc-gadget is this program:
839	http://git.ideasonboard.org/uvc-gadget.git
840
841with these patches:
842
843	http://www.spinics.net/lists/linux-usb/msg99220.html
844
845host::
846
847	luvcview -f yuv
848
84919. PRINTER function
850====================
851
852The function is provided by usb_f_printer.ko module.
853
854Function-specific configfs interface
855------------------------------------
856
857The function name to use when creating the function directory is "printer".
858The printer function provides these attributes in its function directory:
859
860	==========	===========================================
861	pnp_string	Data to be passed to the host in pnp string
862	q_len		Number of requests per endpoint
863	==========	===========================================
864
865Testing the PRINTER function
866----------------------------
867
868The most basic testing:
869
870device: run the gadget::
871
872	# ls -l /devices/virtual/usb_printer_gadget/
873
874should show g_printer<number>.
875
876If udev is active, then /dev/g_printer<number> should appear automatically.
877
878host:
879
880If udev is active, then e.g. /dev/usb/lp0 should appear.
881
882host->device transmission:
883
884device::
885
886	# cat /dev/g_printer<number>
887
888host::
889
890	# cat > /dev/usb/lp0
891
892device->host transmission::
893
894	# cat > /dev/g_printer<number>
895
896host::
897
898	# cat /dev/usb/lp0
899
900More advanced testing can be done with the prn_example
901described in Documentation/usb/gadget_printer.rst.
902
903
90420. UAC1 function (virtual ALSA card, using u_audio API)
905========================================================
906
907The function is provided by usb_f_uac1.ko module.
908It will create a virtual ALSA card and the audio streams are simply
909sinked to and sourced from it.
910
911Function-specific configfs interface
912------------------------------------
913
914The function name to use when creating the function directory is "uac1".
915The uac1 function provides these attributes in its function directory:
916
917	================ ====================================================
918	c_chmask         capture channel mask
919	c_srate          capture sampling rate
920	c_ssize          capture sample size (bytes)
921	c_mute_present   capture mute control enable
922	c_volume_present capture volume control enable
923	c_volume_min     capture volume control min value (in 1/256 dB)
924	c_volume_max     capture volume control max value (in 1/256 dB)
925	c_volume_res     capture volume control resolution (in 1/256 dB)
926	p_chmask         playback channel mask
927	p_srate          playback sampling rate
928	p_ssize          playback sample size (bytes)
929	p_mute_present   playback mute control enable
930	p_volume_present playback volume control enable
931	p_volume_min     playback volume control min value (in 1/256 dB)
932	p_volume_max     playback volume control max value (in 1/256 dB)
933	p_volume_res     playback volume control resolution (in 1/256 dB)
934	req_number       the number of pre-allocated requests for both capture
935	                 and playback
936	================ ====================================================
937
938The attributes have sane default values.
939
940Testing the UAC1 function
941-------------------------
942
943device: run the gadget
944host: aplay -l # should list our USB Audio Gadget
945
946This function does not require real hardware support, it just
947sends a stream of audio data to/from the host. In order to
948actually hear something at the device side, a command similar
949to this must be used at the device side::
950
951	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
952
953e.g.::
954
955	$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
956	  aplay -D default:CARD=OdroidU3
957