5 This file summarizes information on basic testing of USB functions
12 3. ECM subset function
17 8. MASS STORAGE function
24 15. SOURCESINK function
25 16. UAC1 function (legacy implementation)
29 20. UAC1 function (new API)
35 The function is provided by usb_f_acm.ko module.
37 Function-specific configfs interface
38 ------------------------------------
40 The function name to use when creating the function directory is "acm".
41 The ACM function provides just one attribute in its function directory:
45 The attribute is read-only.
47 There can be at most 4 ACM/generic serial/OBEX ports in the system.
50 Testing the ACM function
51 ------------------------
61 then the other way round
74 The function is provided by usb_f_ecm.ko module.
76 Function-specific configfs interface
77 ------------------------------------
79 The function name to use when creating the function directory is "ecm".
80 The ECM function provides these attributes in its function directory:
82 =============== ==================================================
83 ifname network device interface name associated with this
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 =============== ==================================================
92 and after creating the functions/ecm.<instance name> they contain default
93 values: qmult is 5, dev_addr and host_addr are randomly selected.
94 The ifname can be written to if the function is not bound. A write must be an
95 interface pattern such as "usb%d", which will cause the net core to choose the
96 next free usbX interface. By default, it is set to "usb%d".
98 Testing the ECM function
99 ------------------------
101 Configure IP addresses of the device and the host. Then:
111 3. ECM subset function
112 ======================
114 The function is provided by usb_f_ecm_subset.ko module.
116 Function-specific configfs interface
117 ------------------------------------
119 The function name to use when creating the function directory is "geth".
120 The ECM subset function provides these attributes in its function directory:
122 =============== ==================================================
123 ifname network device interface name associated with this
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 =============== ==================================================
132 and after creating the functions/ecm.<instance name> they contain default
133 values: qmult is 5, dev_addr and host_addr are randomly selected.
134 The ifname can be written to if the function is not bound. A write must be an
135 interface pattern such as "usb%d", which will cause the net core to choose the
136 next free usbX interface. By default, it is set to "usb%d".
138 Testing the ECM subset function
139 -------------------------------
141 Configure IP addresses of the device and the host. Then:
154 The function is provided by usb_f_eem.ko module.
156 Function-specific configfs interface
157 ------------------------------------
159 The function name to use when creating the function directory is "eem".
160 The EEM function provides these attributes in its function directory:
162 =============== ==================================================
163 ifname network device interface name associated with this
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 =============== ==================================================
172 and after creating the functions/eem.<instance name> they contain default
173 values: qmult is 5, dev_addr and host_addr are randomly selected.
174 The ifname can be written to if the function is not bound. A write must be an
175 interface pattern such as "usb%d", which will cause the net core to choose the
176 next free usbX interface. By default, it is set to "usb%d".
178 Testing the EEM function
179 ------------------------
181 Configure IP addresses of the device and the host. Then:
194 The function is provided by usb_f_fs.ko module.
196 Function-specific configfs interface
197 ------------------------------------
199 The function name to use when creating the function directory is "ffs".
200 The function directory is intentionally empty and not modifiable.
202 After creating the directory there is a new instance (a "device") of FunctionFS
203 available in the system. Once a "device" is available, the user should follow
204 the standard procedure for using FunctionFS (mount it, run the userspace
205 process which implements the function proper). The gadget should be enabled
206 by writing a suitable string to usb_gadget/<gadget>/UDC.
208 Testing the FFS function
209 ------------------------
211 On the device: start the function's userspace daemon, enable the gadget
213 On the host: use the USB function provided by the device
218 The function is provided by usb_f_hid.ko module.
220 Function-specific configfs interface
221 ------------------------------------
223 The function name to use when creating the function directory is "hid".
224 The HID function provides these attributes in its function directory:
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 =============== ===========================================
234 For a keyboard the protocol and the subclass are 1, the report_length is 8,
235 while the report_desc is::
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...|
244 Such a sequence of bytes can be stored to the attribute with echo::
246 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
248 Testing the HID function
249 ------------------------
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::
259 $ ./hid_gadget_test /dev/hidg0 keyboard
263 - observe the keystrokes from the gadget
268 The function is provided by usb_f_ss_lb.ko module.
270 Function-specific configfs interface
271 ------------------------------------
273 The function name to use when creating the function directory is "Loopback".
274 The LOOPBACK function provides these attributes in its function directory:
276 =============== =======================
277 qlen depth of loopback queue
278 bulk_buflen buffer length
279 =============== =======================
281 Testing the LOOPBACK function
282 -----------------------------
284 device: run the gadget
286 host: test-usb (tools/usb/testusb.c)
288 8. MASS STORAGE function
289 ========================
291 The function is provided by usb_f_mass_storage.ko module.
293 Function-specific configfs interface
294 ------------------------------------
296 The function name to use when creating the function directory is "mass_storage".
297 The MASS STORAGE function provides these attributes in its directory:
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 =============== ==============================================
309 and a default lun.0 directory corresponding to SCSI LUN #0.
311 A new lun can be added with mkdir::
313 $ mkdir functions/mass_storage.0/partition.5
315 Lun numbering does not have to be continuous, except for lun #0 which is
316 created by default. A maximum of 8 luns can be specified and they all must be
317 named following the <name>.<number> scheme. The numbers can be 0..8.
318 Probably a good convention is to name the luns "lun.<number>",
319 although it is not mandatory.
321 In each lun directory there are the following attribute files:
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
332 cdrom Flag specifying that LUN shall be reported as
334 nofua Flag specifying that FUA flag
336 =============== ==============================================
338 Testing the MASS STORAGE function
339 ---------------------------------
341 device: connect the gadget, enable it
342 host: dmesg, see the USB drives appear (if system configured to automatically
348 The function is provided by usb_f_midi.ko module.
350 Function-specific configfs interface
351 ------------------------------------
353 The function name to use when creating the function directory is "midi".
354 The MIDI function provides these attributes in its function directory:
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 =============== ====================================
365 Testing the MIDI function
366 -------------------------
368 There are two cases: playing a mid from the gadget to
369 the host and playing a mid from the host to the gadget.
371 1) Playing a mid from the gadget to the host:
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
384 Port Client name Port name
387 $ aplaymidi -p 20:0 to_host.mid
389 2) Playing a mid from the host to the gadget
394 Port Client name Port name
397 $ arecordmidi -p 20:0 from_host.mid
402 Port Client name Port name
403 14:0 Midi Through Midi Through Port-0
404 24:0 MIDI Gadget MIDI Gadget MIDI 1
406 $ aplaymidi -p24:0 to_gadget.mid
408 The from_gadget.mid should sound identical to the to_host.mid.
410 The from_host.id should sound identical to the to_gadget.mid.
412 MIDI files can be played to speakers/headphones with e.g. timidity installed::
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
423 $ aplaymidi -p 128:0 file.mid
425 MIDI ports can be logically connected using the aconnect utility, e.g.::
427 $ aconnect 24:0 128:0 # try it on the host
429 After the gadget's MIDI port is connected to timidity's MIDI port,
430 whatever is played at the gadget side with aplaymidi -l is audible
431 in host's speakers/headphones.
436 The function is provided by usb_f_ncm.ko module.
438 Function-specific configfs interface
439 ------------------------------------
441 The function name to use when creating the function directory is "ncm".
442 The NCM function provides these attributes in its function directory:
444 =============== ==================================================
445 ifname network device interface name associated with this
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 =============== ==================================================
454 and after creating the functions/ncm.<instance name> they contain default
455 values: qmult is 5, dev_addr and host_addr are randomly selected.
456 The ifname can be written to if the function is not bound. A write must be an
457 interface pattern such as "usb%d", which will cause the net core to choose the
458 next free usbX interface. By default, it is set to "usb%d".
460 Testing the NCM function
461 ------------------------
463 Configure IP addresses of the device and the host. Then:
476 The function is provided by usb_f_obex.ko module.
478 Function-specific configfs interface
479 ------------------------------------
481 The function name to use when creating the function directory is "obex".
482 The OBEX function provides just one attribute in its function directory:
486 The attribute is read-only.
488 There can be at most 4 ACM/generic serial/OBEX ports in the system.
490 Testing the OBEX function
491 -------------------------
495 seriald -f /dev/ttyGS<Y> -s 1024
499 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
500 -t<out endpoint addr> -r<in endpoint addr>
502 where seriald and serialc are Felipe's utilities found here:
504 https://github.com/felipebalbi/usb-tools.git master
509 The function is provided by usb_f_phonet.ko module.
511 Function-specific configfs interface
512 ------------------------------------
514 The function name to use when creating the function directory is "phonet".
515 The PHONET function provides just one attribute in its function directory:
517 =============== ==================================================
518 ifname network device interface name associated with this
520 =============== ==================================================
522 Testing the PHONET function
523 ---------------------------
525 It is not possible to test the SOCK_STREAM protocol without a specific piece
526 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
527 in the past I had to apply the patch mentioned here:
529 http://www.spinics.net/lists/linux-usb/msg85689.html
531 These tools are required:
533 git://git.gitorious.org/meego-cellular/phonet-utils.git
537 $ ./phonet -a 0x10 -i usbpn0
538 $ ./pnroute add 0x6c usbpn0
539 $./pnroute add 0x10 usbpn0
544 $ ./phonet -a 0x6c -i upnlink0
545 $ ./pnroute add 0x10 upnlink0
546 $ ifconfig upnlink0 up
548 Then a test program can be used::
550 http://www.spinics.net/lists/linux-usb/msg85690.html
554 $ ./pnxmit -a 0x6c -r
558 $ ./pnxmit -a 0x10 -s 0x6c
560 As a result some data should be sent from host to device.
561 Then the other way round:
565 $ ./pnxmit -a 0x10 -r
569 $ ./pnxmit -a 0x6c -s 0x10
574 The function is provided by usb_f_rndis.ko module.
576 Function-specific configfs interface
577 ------------------------------------
579 The function name to use when creating the function directory is "rndis".
580 The RNDIS function provides these attributes in its function directory:
582 =============== ==================================================
583 ifname network device interface name associated with this
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 =============== ==================================================
592 and after creating the functions/rndis.<instance name> they contain default
593 values: qmult is 5, dev_addr and host_addr are randomly selected.
594 The ifname can be written to if the function is not bound. A write must be an
595 interface pattern such as "usb%d", which will cause the net core to choose the
596 next free usbX interface. By default, it is set to "usb%d".
598 Testing the RNDIS function
599 --------------------------
601 Configure IP addresses of the device and the host. Then:
614 The function is provided by usb_f_gser.ko module.
616 Function-specific configfs interface
617 ------------------------------------
619 The function name to use when creating the function directory is "gser".
620 The SERIAL function provides just one attribute in its function directory:
624 The attribute is read-only.
626 There can be at most 4 ACM/generic serial/OBEX ports in the system.
628 Testing the SERIAL function
629 ---------------------------
634 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
644 then the other way round
654 15. SOURCESINK function
655 =======================
657 The function is provided by usb_f_ss_lb.ko module.
659 Function-specific configfs interface
660 ------------------------------------
662 The function name to use when creating the function directory is "SourceSink".
663 The SOURCESINK function provides these attributes in its function directory:
665 =============== ==================================
666 pattern 0 (all zeros), 1 (mod63), 2 (none)
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 =============== ==================================
676 Testing the SOURCESINK function
677 -------------------------------
679 device: run the gadget
681 host: test-usb (tools/usb/testusb.c)
684 16. UAC1 function (legacy implementation)
685 =========================================
687 The function is provided by usb_f_uac1_legacy.ko module.
689 Function-specific configfs interface
690 ------------------------------------
692 The function name to use when creating the function directory
694 The uac1 function provides these attributes in its function directory:
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 =============== ====================================
705 The attributes have sane default values.
707 Testing the UAC1 function
708 -------------------------
710 device: run the gadget
714 aplay -l # should list our USB Audio Gadget
719 The function is provided by usb_f_uac2.ko module.
721 Function-specific configfs interface
722 ------------------------------------
724 The function name to use when creating the function directory is "uac2".
725 The uac2 function provides these attributes in its function directory:
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 fb_max maximum extra bandwidth in async mode
733 p_chmask playback channel mask
734 p_srate playback sampling rate
735 p_ssize playback sample size (bytes)
736 req_number the number of pre-allocated request for both capture
738 =============== ====================================================
740 The attributes have sane default values.
742 Testing the UAC2 function
743 -------------------------
745 device: run the gadget
746 host: aplay -l # should list our USB Audio Gadget
748 This function does not require real hardware support, it just
749 sends a stream of audio data to/from the host. In order to
750 actually hear something at the device side, a command similar
751 to this must be used at the device side::
753 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
757 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
758 aplay -D default:CARD=OdroidU3
763 The function is provided by usb_f_uvc.ko module.
765 Function-specific configfs interface
766 ------------------------------------
768 The function name to use when creating the function directory is "uvc".
769 The uvc function provides these attributes in its function directory:
771 =================== ================================================
772 streaming_interval interval for polling endpoint for data transfers
773 streaming_maxburst bMaxBurst for super speed companion descriptor
774 streaming_maxpacket maximum packet size this endpoint is capable of
775 sending or receiving when this configuration is
777 =================== ================================================
779 There are also "control" and "streaming" subdirectories, each of which contain
780 a number of their subdirectories. There are some sane defaults provided, but
781 the user must provide the following:
783 ================== ====================================================
784 control header create in control/header, link from control/class/fs
785 and/or control/class/ss
786 streaming header create in streaming/header, link from
787 streaming/class/fs and/or streaming/class/hs and/or
789 format description create in streaming/mjpeg and/or
790 streaming/uncompressed
791 frame description create in streaming/mjpeg/<format> and/or in
792 streaming/uncompressed/<format>
793 ================== ====================================================
795 Each frame description contains frame interval specification, and each
796 such specification consists of a number of lines with an inverval value
797 in each line. The rules stated above are best illustrated with an example::
799 # mkdir functions/uvc.usb0/control/header/h
800 # cd functions/uvc.usb0/control/
801 # ln -s header/h class/fs
802 # ln -s header/h class/ss
803 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
804 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
809 # cd $GADGET_CONFIGFS_ROOT
810 # mkdir functions/uvc.usb0/streaming/header/h
811 # cd functions/uvc.usb0/streaming/header/h
812 # ln -s ../../uncompressed/u
814 # ln -s ../../header/h
816 # ln -s ../../header/h
818 # ln -s ../../header/h
821 Testing the UVC function
822 ------------------------
824 device: run the gadget, modprobe vivid::
826 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
828 where uvc-gadget is this program:
829 http://git.ideasonboard.org/uvc-gadget.git
833 http://www.spinics.net/lists/linux-usb/msg99220.html
842 The function is provided by usb_f_printer.ko module.
844 Function-specific configfs interface
845 ------------------------------------
847 The function name to use when creating the function directory is "printer".
848 The printer function provides these attributes in its function directory:
850 ========== ===========================================
851 pnp_string Data to be passed to the host in pnp string
852 q_len Number of requests per endpoint
853 ========== ===========================================
855 Testing the PRINTER function
856 ----------------------------
858 The most basic testing:
860 device: run the gadget::
862 # ls -l /devices/virtual/usb_printer_gadget/
864 should show g_printer<number>.
866 If udev is active, then /dev/g_printer<number> should appear automatically.
870 If udev is active, then e.g. /dev/usb/lp0 should appear.
872 host->device transmission:
876 # cat /dev/g_printer<number>
882 device->host transmission::
884 # cat > /dev/g_printer<number>
890 More advanced testing can be done with the prn_example
891 described in Documentation/usb/gadget_printer.rst.
894 20. UAC1 function (virtual ALSA card, using u_audio API)
895 ========================================================
897 The function is provided by usb_f_uac1.ko module.
898 It will create a virtual ALSA card and the audio streams are simply
899 sinked to and sourced from it.
901 Function-specific configfs interface
902 ------------------------------------
904 The function name to use when creating the function directory is "uac1".
905 The uac1 function provides these attributes in its function directory:
907 ========== ====================================================
908 c_chmask capture channel mask
909 c_srate capture sampling rate
910 c_ssize capture sample size (bytes)
911 p_chmask playback channel mask
912 p_srate playback sampling rate
913 p_ssize playback sample size (bytes)
914 req_number the number of pre-allocated request for both capture
916 ========== ====================================================
918 The attributes have sane default values.
920 Testing the UAC1 function
921 -------------------------
923 device: run the gadget
924 host: aplay -l # should list our USB Audio Gadget
926 This function does not require real hardware support, it just
927 sends a stream of audio data to/from the host. In order to
928 actually hear something at the device side, a command similar
929 to this must be used at the device side::
931 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
935 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
936 aplay -D default:CARD=OdroidU3