About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / gadget-testing.txt




Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.

1	This file summarizes information on basic testing of USB functions
2	provided by gadgets.
3	
4	1. ACM function
5	2. ECM function
6	3. ECM subset function
7	4. EEM function
8	5. FFS function
9	6. HID function
10	7. LOOPBACK function
11	8. MASS STORAGE function
12	9. MIDI function
13	10. NCM function
14	11. OBEX function
15	12. PHONET function
16	13. RNDIS function
17	14. SERIAL function
18	15. SOURCESINK function
19	16. UAC1 function
20	17. UAC2 function
21	18. UVC function
22	19. PRINTER function
23	
24	
25	1. ACM function
26	===============
27	
28	The function is provided by usb_f_acm.ko module.
29	
30	Function-specific configfs interface
31	------------------------------------
32	
33	The function name to use when creating the function directory is "acm".
34	The ACM function provides just one attribute in its function directory:
35	
36		port_num
37	
38	The attribute is read-only.
39	
40	There can be at most 4 ACM/generic serial/OBEX ports in the system.
41	
42	
43	Testing the ACM function
44	------------------------
45	
46	On the host: cat > /dev/ttyACM<X>
47	On the device : cat /dev/ttyGS<Y>
48	
49	then the other way round
50	
51	On the device: cat > /dev/ttyGS<Y>
52	On the host: cat /dev/ttyACM<X>
53	
54	2. ECM function
55	===============
56	
57	The function is provided by usb_f_ecm.ko module.
58	
59	Function-specific configfs interface
60	------------------------------------
61	
62	The function name to use when creating the function directory is "ecm".
63	The ECM function provides these attributes in its function directory:
64	
65		ifname		- network device interface name associated with this
66				function instance
67		qmult		- queue length multiplier for high and super speed
68		host_addr	- MAC address of host's end of this
69				Ethernet over USB link
70		dev_addr	- MAC address of device's end of this
71				Ethernet over USB link
72	
73	and after creating the functions/ecm.<instance name> they contain default
74	values: qmult is 5, dev_addr and host_addr are randomly selected.
75	Except for ifname they can be written to until the function is linked to a
76	configuration. The ifname is read-only and contains the name of the interface
77	which was assigned by the net core, e. g. usb0.
78	
79	Testing the ECM function
80	------------------------
81	
82	Configure IP addresses of the device and the host. Then:
83	
84	On the device: ping <host's IP>
85	On the host: ping <device's IP>
86	
87	3. ECM subset function
88	======================
89	
90	The function is provided by usb_f_ecm_subset.ko module.
91	
92	Function-specific configfs interface
93	------------------------------------
94	
95	The function name to use when creating the function directory is "geth".
96	The ECM subset function provides these attributes in its function directory:
97	
98		ifname		- network device interface name associated with this
99				function instance
100		qmult		- queue length multiplier for high and super speed
101		host_addr	- MAC address of host's end of this
102				Ethernet over USB link
103		dev_addr	- MAC address of device's end of this
104				Ethernet over USB link
105	
106	and after creating the functions/ecm.<instance name> they contain default
107	values: qmult is 5, dev_addr and host_addr are randomly selected.
108	Except for ifname they can be written to until the function is linked to a
109	configuration. The ifname is read-only and contains the name of the interface
110	which was assigned by the net core, e. g. usb0.
111	
112	Testing the ECM subset function
113	-------------------------------
114	
115	Configure IP addresses of the device and the host. Then:
116	
117	On the device: ping <host's IP>
118	On the host: ping <device's IP>
119	
120	4. EEM function
121	===============
122	
123	The function is provided by usb_f_eem.ko module.
124	
125	Function-specific configfs interface
126	------------------------------------
127	
128	The function name to use when creating the function directory is "eem".
129	The EEM function provides these attributes in its function directory:
130	
131		ifname		- network device interface name associated with this
132				function instance
133		qmult		- queue length multiplier for high and super speed
134		host_addr	- MAC address of host's end of this
135				Ethernet over USB link
136		dev_addr	- MAC address of device's end of this
137				Ethernet over USB link
138	
139	and after creating the functions/eem.<instance name> they contain default
140	values: qmult is 5, dev_addr and host_addr are randomly selected.
141	Except for ifname they can be written to until the function is linked to a
142	configuration. The ifname is read-only and contains the name of the interface
143	which was assigned by the net core, e. g. usb0.
144	
145	Testing the EEM function
146	------------------------
147	
148	Configure IP addresses of the device and the host. Then:
149	
150	On the device: ping <host's IP>
151	On the host: ping <device's IP>
152	
153	5. FFS function
154	===============
155	
156	The function is provided by usb_f_fs.ko module.
157	
158	Function-specific configfs interface
159	------------------------------------
160	
161	The function name to use when creating the function directory is "ffs".
162	The function directory is intentionally empty and not modifiable.
163	
164	After creating the directory there is a new instance (a "device") of FunctionFS
165	available in the system. Once a "device" is available, the user should follow
166	the standard procedure for using FunctionFS (mount it, run the userspace
167	process which implements the function proper). The gadget should be enabled
168	by writing a suitable string to usb_gadget/<gadget>/UDC.
169	
170	Testing the FFS function
171	------------------------
172	
173	On the device: start the function's userspace daemon, enable the gadget
174	On the host: use the USB function provided by the device
175	
176	6. HID function
177	===============
178	
179	The function is provided by usb_f_hid.ko module.
180	
181	Function-specific configfs interface
182	------------------------------------
183	
184	The function name to use when creating the function directory is "hid".
185	The HID function provides these attributes in its function directory:
186	
187		protocol	- HID protocol to use
188		report_desc	- data to be used in HID reports, except data
189				passed with /dev/hidg<X>
190		report_length	- HID report length
191		subclass	- HID subclass to use
192	
193	For a keyboard the protocol and the subclass are 1, the report_length is 8,
194	while the report_desc is:
195	
196	$ hd my_report_desc
197	00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
198	00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
199	00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
200	00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
201	0000003f
202	
203	Such a sequence of bytes can be stored to the attribute with echo:
204	
205	$ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
206	
207	Testing the HID function
208	------------------------
209	
210	Device:
211	- create the gadget
212	- connect the gadget to a host, preferably not the one used
213	to control the gadget
214	- run a program which writes to /dev/hidg<N>, e.g.
215	a userspace program found in Documentation/usb/gadget_hid.txt:
216	
217	$ ./hid_gadget_test /dev/hidg0 keyboard
218	
219	Host:
220	- observe the keystrokes from the gadget
221	
222	7. LOOPBACK function
223	====================
224	
225	The function is provided by usb_f_ss_lb.ko module.
226	
227	Function-specific configfs interface
228	------------------------------------
229	
230	The function name to use when creating the function directory is "Loopback".
231	The LOOPBACK function provides these attributes in its function directory:
232	
233		qlen		- depth of loopback queue
234		bulk_buflen	- buffer length
235	
236	Testing the LOOPBACK function
237	-----------------------------
238	
239	device: run the gadget
240	host: test-usb (tools/usb/testusb.c)
241	
242	8. MASS STORAGE function
243	========================
244	
245	The function is provided by usb_f_mass_storage.ko module.
246	
247	Function-specific configfs interface
248	------------------------------------
249	
250	The function name to use when creating the function directory is "mass_storage".
251	The MASS STORAGE function provides these attributes in its directory:
252	files:
253	
254		stall		- Set to permit function to halt bulk endpoints.
255				Disabled on some USB devices known not to work
256				correctly. You should set it to true.
257		num_buffers	- Number of pipeline buffers. Valid numbers
258				are 2..4. Available only if
259				CONFIG_USB_GADGET_DEBUG_FILES is set.
260	
261	and a default lun.0 directory corresponding to SCSI LUN #0.
262	
263	A new lun can be added with mkdir:
264	
265	$ mkdir functions/mass_storage.0/partition.5
266	
267	Lun numbering does not have to be continuous, except for lun #0 which is
268	created by default. A maximum of 8 luns can be specified and they all must be
269	named following the <name>.<number> scheme. The numbers can be 0..8.
270	Probably a good convention is to name the luns "lun.<number>",
271	although it is not mandatory.
272	
273	In each lun directory there are the following attribute files:
274	
275		file		- The path to the backing file for the LUN.
276				Required if LUN is not marked as removable.
277		ro		- Flag specifying access to the LUN shall be
278				read-only. This is implied if CD-ROM emulation
279				is enabled as well as when it was impossible
280				to open "filename" in R/W mode.
281		removable	- Flag specifying that LUN shall be indicated as
282				being removable.
283		cdrom		- Flag specifying that LUN shall be reported as
284				being a CD-ROM.
285		nofua		- Flag specifying that FUA flag
286				in SCSI WRITE(10,12)
287	
288	Testing the MASS STORAGE function
289	---------------------------------
290	
291	device: connect the gadget, enable it
292	host: dmesg, see the USB drives appear (if system configured to automatically
293	mount)
294	
295	9. MIDI function
296	================
297	
298	The function is provided by usb_f_midi.ko module.
299	
300	Function-specific configfs interface
301	------------------------------------
302	
303	The function name to use when creating the function directory is "midi".
304	The MIDI function provides these attributes in its function directory:
305	
306		buflen		- MIDI buffer length
307		id		- ID string for the USB MIDI adapter
308		in_ports	- number of MIDI input ports
309		index		- index value for the USB MIDI adapter
310		out_ports	- number of MIDI output ports
311		qlen		- USB read request queue length
312	
313	Testing the MIDI function
314	-------------------------
315	
316	There are two cases: playing a mid from the gadget to
317	the host and playing a mid from the host to the gadget.
318	
319	1) Playing a mid from the gadget to the host
320	host)
321	
322	$ arecordmidi -l
323	 Port    Client name                      Port name
324	 14:0    Midi Through                     Midi Through Port-0
325	 24:0    MIDI Gadget                      MIDI Gadget MIDI 1
326	$ arecordmidi -p 24:0 from_gadget.mid
327	
328	gadget)
329	
330	$ aplaymidi -l
331	 Port    Client name                      Port name
332	 20:0    f_midi                           f_midi
333	
334	$ aplaymidi -p 20:0 to_host.mid
335	
336	2) Playing a mid from the host to the gadget
337	gadget)
338	
339	$ arecordmidi -l
340	 Port    Client name                      Port name
341	 20:0    f_midi                           f_midi
342	
343	$ arecordmidi -p 20:0 from_host.mid
344	
345	host)
346	
347	$ aplaymidi -l
348	 Port    Client name                      Port name
349	 14:0    Midi Through                     Midi Through Port-0
350	 24:0    MIDI Gadget                      MIDI Gadget MIDI 1
351	
352	$ aplaymidi -p24:0 to_gadget.mid
353	
354	The from_gadget.mid should sound identical to the to_host.mid.
355	The from_host.id should sound identical to the to_gadget.mid.
356	
357	MIDI files can be played to speakers/headphones with e.g. timidity installed
358	
359	$ aplaymidi -l
360	 Port    Client name                      Port name
361	 14:0    Midi Through                     Midi Through Port-0
362	 24:0    MIDI Gadget                      MIDI Gadget MIDI 1
363	128:0    TiMidity                         TiMidity port 0
364	128:1    TiMidity                         TiMidity port 1
365	128:2    TiMidity                         TiMidity port 2
366	128:3    TiMidity                         TiMidity port 3
367	
368	$ aplaymidi -p 128:0 file.mid
369	
370	MIDI ports can be logically connected using the aconnect utility, e.g.:
371	
372	$ aconnect 24:0 128:0 # try it on the host
373	
374	After the gadget's MIDI port is connected to timidity's MIDI port,
375	whatever is played at the gadget side with aplaymidi -l is audible
376	in host's speakers/headphones.
377	
378	10. NCM function
379	================
380	
381	The function is provided by usb_f_ncm.ko module.
382	
383	Function-specific configfs interface
384	------------------------------------
385	
386	The function name to use when creating the function directory is "ncm".
387	The NCM function provides these attributes in its function directory:
388	
389		ifname		- network device interface name associated with this
390				function instance
391		qmult		- queue length multiplier for high and super speed
392		host_addr	- MAC address of host's end of this
393				Ethernet over USB link
394		dev_addr	- MAC address of device's end of this
395				Ethernet over USB link
396	
397	and after creating the functions/ncm.<instance name> they contain default
398	values: qmult is 5, dev_addr and host_addr are randomly selected.
399	Except for ifname they can be written to until the function is linked to a
400	configuration. The ifname is read-only and contains the name of the interface
401	which was assigned by the net core, e. g. usb0.
402	
403	Testing the NCM function
404	------------------------
405	
406	Configure IP addresses of the device and the host. Then:
407	
408	On the device: ping <host's IP>
409	On the host: ping <device's IP>
410	
411	11. OBEX function
412	=================
413	
414	The function is provided by usb_f_obex.ko module.
415	
416	Function-specific configfs interface
417	------------------------------------
418	
419	The function name to use when creating the function directory is "obex".
420	The OBEX function provides just one attribute in its function directory:
421	
422		port_num
423	
424	The attribute is read-only.
425	
426	There can be at most 4 ACM/generic serial/OBEX ports in the system.
427	
428	Testing the OBEX function
429	-------------------------
430	
431	On device: seriald -f /dev/ttyGS<Y> -s 1024
432	On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
433	             -t<out endpoint addr> -r<in endpoint addr>
434	
435	where seriald and serialc are Felipe's utilities found here:
436	
437	https://github.com/felipebalbi/usb-tools.git master
438	
439	12. PHONET function
440	===================
441	
442	The function is provided by usb_f_phonet.ko module.
443	
444	Function-specific configfs interface
445	------------------------------------
446	
447	The function name to use when creating the function directory is "phonet".
448	The PHONET function provides just one attribute in its function directory:
449	
450		ifname		- network device interface name associated with this
451				function instance
452	
453	Testing the PHONET function
454	---------------------------
455	
456	It is not possible to test the SOCK_STREAM protocol without a specific piece
457	of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
458	in the past I had to apply the patch mentioned here:
459	
460	http://www.spinics.net/lists/linux-usb/msg85689.html
461	
462	These tools are required:
463	
464	git://git.gitorious.org/meego-cellular/phonet-utils.git
465	
466	On the host:
467	
468	$ ./phonet -a 0x10 -i usbpn0
469	$ ./pnroute add 0x6c usbpn0
470	$./pnroute add 0x10 usbpn0
471	$ ifconfig usbpn0 up
472	
473	On the device:
474	
475	$ ./phonet -a 0x6c -i upnlink0
476	$ ./pnroute add 0x10 upnlink0
477	$ ifconfig upnlink0 up
478	
479	Then a test program can be used:
480	
481	http://www.spinics.net/lists/linux-usb/msg85690.html
482	
483	On the device:
484	
485	$ ./pnxmit -a 0x6c -r
486	
487	On the host:
488	
489	$ ./pnxmit -a 0x10 -s 0x6c
490	
491	As a result some data should be sent from host to device.
492	Then the other way round:
493	
494	On the host:
495	
496	$ ./pnxmit -a 0x10 -r
497	
498	On the device:
499	
500	$ ./pnxmit -a 0x6c -s 0x10
501	
502	13. RNDIS function
503	==================
504	
505	The function is provided by usb_f_rndis.ko module.
506	
507	Function-specific configfs interface
508	------------------------------------
509	
510	The function name to use when creating the function directory is "rndis".
511	The RNDIS function provides these attributes in its function directory:
512	
513		ifname		- network device interface name associated with this
514				function instance
515		qmult		- queue length multiplier for high and super speed
516		host_addr	- MAC address of host's end of this
517				Ethernet over USB link
518		dev_addr	- MAC address of device's end of this
519				Ethernet over USB link
520	
521	and after creating the functions/rndis.<instance name> they contain default
522	values: qmult is 5, dev_addr and host_addr are randomly selected.
523	Except for ifname they can be written to until the function is linked to a
524	configuration. The ifname is read-only and contains the name of the interface
525	which was assigned by the net core, e. g. usb0.
526	
527	Testing the RNDIS function
528	--------------------------
529	
530	Configure IP addresses of the device and the host. Then:
531	
532	On the device: ping <host's IP>
533	On the host: ping <device's IP>
534	
535	14. SERIAL function
536	===================
537	
538	The function is provided by usb_f_gser.ko module.
539	
540	Function-specific configfs interface
541	------------------------------------
542	
543	The function name to use when creating the function directory is "gser".
544	The SERIAL function provides just one attribute in its function directory:
545	
546		port_num
547	
548	The attribute is read-only.
549	
550	There can be at most 4 ACM/generic serial/OBEX ports in the system.
551	
552	Testing the SERIAL function
553	---------------------------
554	
555	On host: insmod usbserial
556		 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
557	On host: cat > /dev/ttyUSB<X>
558	On target: cat /dev/ttyGS<Y>
559	
560	then the other way round
561	
562	On target: cat > /dev/ttyGS<Y>
563	On host: cat /dev/ttyUSB<X>
564	
565	15. SOURCESINK function
566	=======================
567	
568	The function is provided by usb_f_ss_lb.ko module.
569	
570	Function-specific configfs interface
571	------------------------------------
572	
573	The function name to use when creating the function directory is "SourceSink".
574	The SOURCESINK function provides these attributes in its function directory:
575	
576		pattern		- 0 (all zeros), 1 (mod63), 2 (none)
577		isoc_interval	- 1..16
578		isoc_maxpacket	- 0 - 1023 (fs), 0 - 1024 (hs/ss)
579		isoc_mult	- 0..2 (hs/ss only)
580		isoc_maxburst	- 0..15 (ss only)
581		bulk_buflen	- buffer length
582		bulk_qlen	- depth of queue for bulk
583		iso_qlen	- depth of queue for iso
584	
585	Testing the SOURCESINK function
586	-------------------------------
587	
588	device: run the gadget
589	host: test-usb (tools/usb/testusb.c)
590	
591	
592	16. UAC1 function
593	=================
594	
595	The function is provided by usb_f_uac1.ko module.
596	
597	Function-specific configfs interface
598	------------------------------------
599	
600	The function name to use when creating the function directory is "uac1".
601	The uac1 function provides these attributes in its function directory:
602	
603		audio_buf_size - audio buffer size
604		fn_cap - capture pcm device file name
605		fn_cntl - control device file name
606		fn_play - playback pcm device file name
607		req_buf_size - ISO OUT endpoint request buffer size
608		req_count - ISO OUT endpoint request count
609	
610	The attributes have sane default values.
611	
612	Testing the UAC1 function
613	-------------------------
614	
615	device: run the gadget
616	host: aplay -l # should list our USB Audio Gadget
617	
618	17. UAC2 function
619	=================
620	
621	The function is provided by usb_f_uac2.ko module.
622	
623	Function-specific configfs interface
624	------------------------------------
625	
626	The function name to use when creating the function directory is "uac2".
627	The uac2 function provides these attributes in its function directory:
628	
629		c_chmask - capture channel mask
630		c_srate - capture sampling rate
631		c_ssize - capture sample size (bytes)
632		p_chmask - playback channel mask
633		p_srate - playback sampling rate
634		p_ssize - playback sample size (bytes)
635	
636	The attributes have sane default values.
637	
638	Testing the UAC2 function
639	-------------------------
640	
641	device: run the gadget
642	host: aplay -l # should list our USB Audio Gadget
643	
644	This function does not require real hardware support, it just
645	sends a stream of audio data to/from the host. In order to
646	actually hear something at the device side, a command similar
647	to this must be used at the device side:
648	
649	$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
650	
651	e.g.:
652	
653	$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
654	aplay -D default:CARD=OdroidU3
655	
656	18. UVC function
657	================
658	
659	The function is provided by usb_f_uvc.ko module.
660	
661	Function-specific configfs interface
662	------------------------------------
663	
664	The function name to use when creating the function directory is "uvc".
665	The uvc function provides these attributes in its function directory:
666	
667		streaming_interval - interval for polling endpoint for data transfers
668		streaming_maxburst - bMaxBurst for super speed companion descriptor
669		streaming_maxpacket - maximum packet size this endpoint is capable of
670				      sending or receiving when this configuration is
671				      selected
672	
673	There are also "control" and "streaming" subdirectories, each of which contain
674	a number of their subdirectories. There are some sane defaults provided, but
675	the user must provide the following:
676	
677		control header - create in control/header, link from control/class/fs
678				and/or control/class/ss
679		streaming header - create in streaming/header, link from
680				streaming/class/fs and/or streaming/class/hs and/or
681				streaming/class/ss
682		format description - create in streaming/mjpeg and/or
683				streaming/uncompressed
684		frame description - create in streaming/mjpeg/<format> and/or in
685				streaming/uncompressed/<format>
686	
687	Each frame description contains frame interval specification, and each
688	such specification consists of a number of lines with an inverval value
689	in each line. The rules stated above are best illustrated with an example:
690	
691	# mkdir functions/uvc.usb0/control/header/h
692	# cd functions/uvc.usb0/control/header/h
693	# ln -s header/h class/fs
694	# ln -s header/h class/ss
695	# mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
696	# cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
697	666666
698	1000000
699	5000000
700	EOF
701	# cd $GADGET_CONFIGFS_ROOT
702	# mkdir functions/uvc.usb0/streaming/header/h
703	# cd functions/uvc.usb0/streaming/header/h
704	# ln -s ../../uncompressed/u
705	# cd ../../class/fs
706	# ln -s ../../header/h
707	# cd ../../class/hs
708	# ln -s ../../header/h
709	# cd ../../class/ss
710	# ln -s ../../header/h
711	
712	
713	Testing the UVC function
714	------------------------
715	
716	device: run the gadget, modprobe vivid
717	
718	# uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
719	
720	where uvc-gadget is this program:
721	http://git.ideasonboard.org/uvc-gadget.git
722	
723	with these patches:
724	http://www.spinics.net/lists/linux-usb/msg99220.html
725	
726	host: luvcview -f yuv
727	
728	19. PRINTER function
729	====================
730	
731	The function is provided by usb_f_printer.ko module.
732	
733	Function-specific configfs interface
734	------------------------------------
735	
736	The function name to use when creating the function directory is "printer".
737	The printer function provides these attributes in its function directory:
738	
739		pnp_string	- Data to be passed to the host in pnp string
740		q_len		- Number of requests per endpoint
741	
742	Testing the PRINTER function
743	----------------------------
744	
745	The most basic testing:
746	
747	device: run the gadget
748	# ls -l /devices/virtual/usb_printer_gadget/
749	
750	should show g_printer<number>.
751	
752	If udev is active, then /dev/g_printer<number> should appear automatically.
753	
754	host:
755	
756	If udev is active, then e.g. /dev/usb/lp0 should appear.
757	
758	host->device transmission:
759	
760	device:
761	# cat /dev/g_printer<number>
762	host:
763	# cat > /dev/usb/lp0
764	
765	device->host transmission:
766	
767	# cat > /dev/g_printer<number>
768	host:
769	# cat /dev/usb/lp0
770	
771	More advanced testing can be done with the prn_example
772	described in Documentation/usb/gadget-printer.txt.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.