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 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
748 ================ ====================================================
750 The attributes have sane default values.
752 Testing the UAC2 function
753 -------------------------
755 device: run the gadget
756 host: aplay -l # should list our USB Audio Gadget
758 This function does not require real hardware support, it just
759 sends a stream of audio data to/from the host. In order to
760 actually hear something at the device side, a command similar
761 to this must be used at the device side::
763 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
767 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
768 aplay -D default:CARD=OdroidU3
773 The function is provided by usb_f_uvc.ko module.
775 Function-specific configfs interface
776 ------------------------------------
778 The function name to use when creating the function directory is "uvc".
779 The uvc function provides these attributes in its function directory:
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
787 =================== ================================================
789 There are also "control" and "streaming" subdirectories, each of which contain
790 a number of their subdirectories. There are some sane defaults provided, but
791 the user must provide the following:
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
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 ================== ====================================================
805 Each frame description contains frame interval specification, and each
806 such specification consists of a number of lines with an inverval value
807 in each line. The rules stated above are best illustrated with an example::
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
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
824 # ln -s ../../header/h
826 # ln -s ../../header/h
828 # ln -s ../../header/h
831 Testing the UVC function
832 ------------------------
834 device: run the gadget, modprobe vivid::
836 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
838 where uvc-gadget is this program:
839 http://git.ideasonboard.org/uvc-gadget.git
843 http://www.spinics.net/lists/linux-usb/msg99220.html
852 The function is provided by usb_f_printer.ko module.
854 Function-specific configfs interface
855 ------------------------------------
857 The function name to use when creating the function directory is "printer".
858 The printer function provides these attributes in its function directory:
860 ========== ===========================================
861 pnp_string Data to be passed to the host in pnp string
862 q_len Number of requests per endpoint
863 ========== ===========================================
865 Testing the PRINTER function
866 ----------------------------
868 The most basic testing:
870 device: run the gadget::
872 # ls -l /devices/virtual/usb_printer_gadget/
874 should show g_printer<number>.
876 If udev is active, then /dev/g_printer<number> should appear automatically.
880 If udev is active, then e.g. /dev/usb/lp0 should appear.
882 host->device transmission:
886 # cat /dev/g_printer<number>
892 device->host transmission::
894 # cat > /dev/g_printer<number>
900 More advanced testing can be done with the prn_example
901 described in Documentation/usb/gadget_printer.rst.
904 20. UAC1 function (virtual ALSA card, using u_audio API)
905 ========================================================
907 The function is provided by usb_f_uac1.ko module.
908 It will create a virtual ALSA card and the audio streams are simply
909 sinked to and sourced from it.
911 Function-specific configfs interface
912 ------------------------------------
914 The function name to use when creating the function directory is "uac1".
915 The uac1 function provides these attributes in its function directory:
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 request for both capture
936 ================ ====================================================
938 The attributes have sane default values.
940 Testing the UAC1 function
941 -------------------------
943 device: run the gadget
944 host: aplay -l # should list our USB Audio Gadget
946 This function does not require real hardware support, it just
947 sends a stream of audio data to/from the host. In order to
948 actually hear something at the device side, a command similar
949 to this must be used at the device side::
951 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
955 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
956 aplay -D default:CARD=OdroidU3