1 This file summarizes information on basic testing of USB functions
11 8. MASS STORAGE function
18 15. SOURCESINK function
19 16. UAC1 function (legacy implementation)
23 20. UAC1 function (new API)
29 The function is provided by usb_f_acm.ko module.
31 Function-specific configfs interface
32 ------------------------------------
34 The function name to use when creating the function directory is "acm".
35 The ACM function provides just one attribute in its function directory:
39 The attribute is read-only.
41 There can be at most 4 ACM/generic serial/OBEX ports in the system.
44 Testing the ACM function
45 ------------------------
47 On the host: cat > /dev/ttyACM<X>
48 On the device : cat /dev/ttyGS<Y>
50 then the other way round
52 On the device: cat > /dev/ttyGS<Y>
53 On the host: cat /dev/ttyACM<X>
58 The function is provided by usb_f_ecm.ko module.
60 Function-specific configfs interface
61 ------------------------------------
63 The function name to use when creating the function directory is "ecm".
64 The ECM function provides these attributes in its function directory:
66 ifname - network device interface name associated with this
68 qmult - queue length multiplier for high and super speed
69 host_addr - MAC address of host's end of this
70 Ethernet over USB link
71 dev_addr - MAC address of device's end of this
72 Ethernet over USB link
74 and after creating the functions/ecm.<instance name> they contain default
75 values: qmult is 5, dev_addr and host_addr are randomly selected.
76 Except for ifname they can be written to until the function is linked to a
77 configuration. The ifname is read-only and contains the name of the interface
78 which was assigned by the net core, e. g. usb0.
80 Testing the ECM function
81 ------------------------
83 Configure IP addresses of the device and the host. Then:
85 On the device: ping <host's IP>
86 On the host: ping <device's IP>
88 3. ECM subset function
89 ======================
91 The function is provided by usb_f_ecm_subset.ko module.
93 Function-specific configfs interface
94 ------------------------------------
96 The function name to use when creating the function directory is "geth".
97 The ECM subset function provides these attributes in its function directory:
99 ifname - network device interface name associated with this
101 qmult - queue length multiplier for high and super speed
102 host_addr - MAC address of host's end of this
103 Ethernet over USB link
104 dev_addr - MAC address of device's end of this
105 Ethernet over USB link
107 and after creating the functions/ecm.<instance name> they contain default
108 values: qmult is 5, dev_addr and host_addr are randomly selected.
109 Except for ifname they can be written to until the function is linked to a
110 configuration. The ifname is read-only and contains the name of the interface
111 which was assigned by the net core, e. g. usb0.
113 Testing the ECM subset function
114 -------------------------------
116 Configure IP addresses of the device and the host. Then:
118 On the device: ping <host's IP>
119 On the host: ping <device's IP>
124 The function is provided by usb_f_eem.ko module.
126 Function-specific configfs interface
127 ------------------------------------
129 The function name to use when creating the function directory is "eem".
130 The EEM function provides these attributes in its function directory:
132 ifname - network device interface name associated with this
134 qmult - queue length multiplier for high and super speed
135 host_addr - MAC address of host's end of this
136 Ethernet over USB link
137 dev_addr - MAC address of device's end of this
138 Ethernet over USB link
140 and after creating the functions/eem.<instance name> they contain default
141 values: qmult is 5, dev_addr and host_addr are randomly selected.
142 Except for ifname they can be written to until the function is linked to a
143 configuration. The ifname is read-only and contains the name of the interface
144 which was assigned by the net core, e. g. usb0.
146 Testing the EEM function
147 ------------------------
149 Configure IP addresses of the device and the host. Then:
151 On the device: ping <host's IP>
152 On the host: ping <device's IP>
157 The function is provided by usb_f_fs.ko module.
159 Function-specific configfs interface
160 ------------------------------------
162 The function name to use when creating the function directory is "ffs".
163 The function directory is intentionally empty and not modifiable.
165 After creating the directory there is a new instance (a "device") of FunctionFS
166 available in the system. Once a "device" is available, the user should follow
167 the standard procedure for using FunctionFS (mount it, run the userspace
168 process which implements the function proper). The gadget should be enabled
169 by writing a suitable string to usb_gadget/<gadget>/UDC.
171 Testing the FFS function
172 ------------------------
174 On the device: start the function's userspace daemon, enable the gadget
175 On the host: use the USB function provided by the device
180 The function is provided by usb_f_hid.ko module.
182 Function-specific configfs interface
183 ------------------------------------
185 The function name to use when creating the function directory is "hid".
186 The HID function provides these attributes in its function directory:
188 protocol - HID protocol to use
189 report_desc - data to be used in HID reports, except data
190 passed with /dev/hidg<X>
191 report_length - HID report length
192 subclass - HID subclass to use
194 For a keyboard the protocol and the subclass are 1, the report_length is 8,
195 while the report_desc is:
198 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.|
199 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.|
200 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....|
201 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...|
204 Such a sequence of bytes can be stored to the attribute with echo:
206 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
208 Testing the HID function
209 ------------------------
213 - connect the gadget to a host, preferably not the one used
214 to control the gadget
215 - run a program which writes to /dev/hidg<N>, e.g.
216 a userspace program found in Documentation/usb/gadget_hid.txt:
218 $ ./hid_gadget_test /dev/hidg0 keyboard
221 - observe the keystrokes from the gadget
226 The function is provided by usb_f_ss_lb.ko module.
228 Function-specific configfs interface
229 ------------------------------------
231 The function name to use when creating the function directory is "Loopback".
232 The LOOPBACK function provides these attributes in its function directory:
234 qlen - depth of loopback queue
235 bulk_buflen - buffer length
237 Testing the LOOPBACK function
238 -----------------------------
240 device: run the gadget
241 host: test-usb (tools/usb/testusb.c)
243 8. MASS STORAGE function
244 ========================
246 The function is provided by usb_f_mass_storage.ko module.
248 Function-specific configfs interface
249 ------------------------------------
251 The function name to use when creating the function directory is "mass_storage".
252 The MASS STORAGE function provides these attributes in its directory:
255 stall - Set to permit function to halt bulk endpoints.
256 Disabled on some USB devices known not to work
257 correctly. You should set it to true.
258 num_buffers - Number of pipeline buffers. Valid numbers
259 are 2..4. Available only if
260 CONFIG_USB_GADGET_DEBUG_FILES is set.
262 and a default lun.0 directory corresponding to SCSI LUN #0.
264 A new lun can be added with mkdir:
266 $ mkdir functions/mass_storage.0/partition.5
268 Lun numbering does not have to be continuous, except for lun #0 which is
269 created by default. A maximum of 8 luns can be specified and they all must be
270 named following the <name>.<number> scheme. The numbers can be 0..8.
271 Probably a good convention is to name the luns "lun.<number>",
272 although it is not mandatory.
274 In each lun directory there are the following attribute files:
276 file - The path to the backing file for the LUN.
277 Required if LUN is not marked as removable.
278 ro - Flag specifying access to the LUN shall be
279 read-only. This is implied if CD-ROM emulation
280 is enabled as well as when it was impossible
281 to open "filename" in R/W mode.
282 removable - Flag specifying that LUN shall be indicated as
284 cdrom - Flag specifying that LUN shall be reported as
286 nofua - Flag specifying that FUA flag
289 Testing the MASS STORAGE function
290 ---------------------------------
292 device: connect the gadget, enable it
293 host: dmesg, see the USB drives appear (if system configured to automatically
299 The function is provided by usb_f_midi.ko module.
301 Function-specific configfs interface
302 ------------------------------------
304 The function name to use when creating the function directory is "midi".
305 The MIDI function provides these attributes in its function directory:
307 buflen - MIDI buffer length
308 id - ID string for the USB MIDI adapter
309 in_ports - number of MIDI input ports
310 index - index value for the USB MIDI adapter
311 out_ports - number of MIDI output ports
312 qlen - USB read request queue length
314 Testing the MIDI function
315 -------------------------
317 There are two cases: playing a mid from the gadget to
318 the host and playing a mid from the host to the gadget.
320 1) Playing a mid from the gadget to the host
324 Port Client name Port name
325 14:0 Midi Through Midi Through Port-0
326 24:0 MIDI Gadget MIDI Gadget MIDI 1
327 $ arecordmidi -p 24:0 from_gadget.mid
332 Port Client name Port name
335 $ aplaymidi -p 20:0 to_host.mid
337 2) Playing a mid from the host to the gadget
341 Port Client name Port name
344 $ arecordmidi -p 20:0 from_host.mid
349 Port Client name Port name
350 14:0 Midi Through Midi Through Port-0
351 24:0 MIDI Gadget MIDI Gadget MIDI 1
353 $ aplaymidi -p24:0 to_gadget.mid
355 The from_gadget.mid should sound identical to the to_host.mid.
356 The from_host.id should sound identical to the to_gadget.mid.
358 MIDI files can be played to speakers/headphones with e.g. timidity installed
361 Port Client name Port name
362 14:0 Midi Through Midi Through Port-0
363 24:0 MIDI Gadget MIDI Gadget MIDI 1
364 128:0 TiMidity TiMidity port 0
365 128:1 TiMidity TiMidity port 1
366 128:2 TiMidity TiMidity port 2
367 128:3 TiMidity TiMidity port 3
369 $ aplaymidi -p 128:0 file.mid
371 MIDI ports can be logically connected using the aconnect utility, e.g.:
373 $ aconnect 24:0 128:0 # try it on the host
375 After the gadget's MIDI port is connected to timidity's MIDI port,
376 whatever is played at the gadget side with aplaymidi -l is audible
377 in host's speakers/headphones.
382 The function is provided by usb_f_ncm.ko module.
384 Function-specific configfs interface
385 ------------------------------------
387 The function name to use when creating the function directory is "ncm".
388 The NCM function provides these attributes in its function directory:
390 ifname - network device interface name associated with this
392 qmult - queue length multiplier for high and super speed
393 host_addr - MAC address of host's end of this
394 Ethernet over USB link
395 dev_addr - MAC address of device's end of this
396 Ethernet over USB link
398 and after creating the functions/ncm.<instance name> they contain default
399 values: qmult is 5, dev_addr and host_addr are randomly selected.
400 Except for ifname they can be written to until the function is linked to a
401 configuration. The ifname is read-only and contains the name of the interface
402 which was assigned by the net core, e. g. usb0.
404 Testing the NCM function
405 ------------------------
407 Configure IP addresses of the device and the host. Then:
409 On the device: ping <host's IP>
410 On the host: ping <device's IP>
415 The function is provided by usb_f_obex.ko module.
417 Function-specific configfs interface
418 ------------------------------------
420 The function name to use when creating the function directory is "obex".
421 The OBEX function provides just one attribute in its function directory:
425 The attribute is read-only.
427 There can be at most 4 ACM/generic serial/OBEX ports in the system.
429 Testing the OBEX function
430 -------------------------
432 On device: seriald -f /dev/ttyGS<Y> -s 1024
433 On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
434 -t<out endpoint addr> -r<in endpoint addr>
436 where seriald and serialc are Felipe's utilities found here:
438 https://git.gitorious.org/usb/usb-tools.git master
443 The function is provided by usb_f_phonet.ko module.
445 Function-specific configfs interface
446 ------------------------------------
448 The function name to use when creating the function directory is "phonet".
449 The PHONET function provides just one attribute in its function directory:
451 ifname - network device interface name associated with this
454 Testing the PHONET function
455 ---------------------------
457 It is not possible to test the SOCK_STREAM protocol without a specific piece
458 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
459 in the past I had to apply the patch mentioned here:
461 http://www.spinics.net/lists/linux-usb/msg85689.html
463 These tools are required:
465 git://git.gitorious.org/meego-cellular/phonet-utils.git
469 $ ./phonet -a 0x10 -i usbpn0
470 $ ./pnroute add 0x6c usbpn0
471 $./pnroute add 0x10 usbpn0
476 $ ./phonet -a 0x6c -i upnlink0
477 $ ./pnroute add 0x10 upnlink0
478 $ ifconfig upnlink0 up
480 Then a test program can be used:
482 http://www.spinics.net/lists/linux-usb/msg85690.html
486 $ ./pnxmit -a 0x6c -r
490 $ ./pnxmit -a 0x10 -s 0x6c
492 As a result some data should be sent from host to device.
493 Then the other way round:
497 $ ./pnxmit -a 0x10 -r
501 $ ./pnxmit -a 0x6c -s 0x10
506 The function is provided by usb_f_rndis.ko module.
508 Function-specific configfs interface
509 ------------------------------------
511 The function name to use when creating the function directory is "rndis".
512 The RNDIS function provides these attributes in its function directory:
514 ifname - network device interface name associated with this
516 qmult - queue length multiplier for high and super speed
517 host_addr - MAC address of host's end of this
518 Ethernet over USB link
519 dev_addr - MAC address of device's end of this
520 Ethernet over USB link
522 and after creating the functions/rndis.<instance name> they contain default
523 values: qmult is 5, dev_addr and host_addr are randomly selected.
524 Except for ifname they can be written to until the function is linked to a
525 configuration. The ifname is read-only and contains the name of the interface
526 which was assigned by the net core, e. g. usb0.
528 Testing the RNDIS function
529 --------------------------
531 Configure IP addresses of the device and the host. Then:
533 On the device: ping <host's IP>
534 On the host: ping <device's IP>
539 The function is provided by usb_f_gser.ko module.
541 Function-specific configfs interface
542 ------------------------------------
544 The function name to use when creating the function directory is "gser".
545 The SERIAL function provides just one attribute in its function directory:
549 The attribute is read-only.
551 There can be at most 4 ACM/generic serial/OBEX ports in the system.
553 Testing the SERIAL function
554 ---------------------------
556 On host: insmod usbserial
557 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
558 On host: cat > /dev/ttyUSB<X>
559 On target: cat /dev/ttyGS<Y>
561 then the other way round
563 On target: cat > /dev/ttyGS<Y>
564 On host: cat /dev/ttyUSB<X>
566 15. SOURCESINK function
567 =======================
569 The function is provided by usb_f_ss_lb.ko module.
571 Function-specific configfs interface
572 ------------------------------------
574 The function name to use when creating the function directory is "SourceSink".
575 The SOURCESINK function provides these attributes in its function directory:
577 pattern - 0 (all zeros), 1 (mod63), 2 (none)
578 isoc_interval - 1..16
579 isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss)
580 isoc_mult - 0..2 (hs/ss only)
581 isoc_maxburst - 0..15 (ss only)
582 bulk_buflen - buffer length
584 Testing the SOURCESINK function
585 -------------------------------
587 device: run the gadget
588 host: test-usb (tools/usb/testusb.c)
591 16. UAC1 function (legacy implementation)
594 The function is provided by usb_f_uac1_legacy.ko module.
596 Function-specific configfs interface
597 ------------------------------------
599 The function name to use when creating the function directory
601 The uac1 function provides these attributes in its function directory:
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
610 The attributes have sane default values.
612 Testing the UAC1 function
613 -------------------------
615 device: run the gadget
616 host: aplay -l # should list our USB Audio Gadget
621 The function is provided by usb_f_uac2.ko module.
623 Function-specific configfs interface
624 ------------------------------------
626 The function name to use when creating the function directory is "uac2".
627 The uac2 function provides these attributes in its function directory:
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 req_number - the number of pre-allocated request for both capture
638 The attributes have sane default values.
640 Testing the UAC2 function
641 -------------------------
643 device: run the gadget
644 host: aplay -l # should list our USB Audio Gadget
646 This function does not require real hardware support, it just
647 sends a stream of audio data to/from the host. In order to
648 actually hear something at the device side, a command similar
649 to this must be used at the device side:
651 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
655 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
656 aplay -D default:CARD=OdroidU3
661 The function is provided by usb_f_uvc.ko module.
663 Function-specific configfs interface
664 ------------------------------------
666 The function name to use when creating the function directory is "uvc".
667 The uvc function provides these attributes in its function directory:
669 streaming_interval - interval for polling endpoint for data transfers
670 streaming_maxburst - bMaxBurst for super speed companion descriptor
671 streaming_maxpacket - maximum packet size this endpoint is capable of
672 sending or receiving when this configuration is
675 There are also "control" and "streaming" subdirectories, each of which contain
676 a number of their subdirectories. There are some sane defaults provided, but
677 the user must provide the following:
679 control header - create in control/header, link from control/class/fs
680 and/or control/class/ss
681 streaming header - create in streaming/header, link from
682 streaming/class/fs and/or streaming/class/hs and/or
684 format description - create in streaming/mjpeg and/or
685 streaming/uncompressed
686 frame description - create in streaming/mjpeg/<format> and/or in
687 streaming/uncompressed/<format>
689 Each frame description contains frame interval specification, and each
690 such specification consists of a number of lines with an inverval value
691 in each line. The rules stated above are best illustrated with an example:
693 # mkdir functions/uvc.usb0/control/header/h
694 # cd functions/uvc.usb0/control/header/h
695 # ln -s header/h class/fs
696 # ln -s header/h class/ss
697 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
698 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
703 # cd $GADGET_CONFIGFS_ROOT
704 # mkdir functions/uvc.usb0/streaming/header/h
705 # cd functions/uvc.usb0/streaming/header/h
706 # ln -s ../../uncompressed/u
708 # ln -s ../../header/h
710 # ln -s ../../header/h
712 # ln -s ../../header/h
715 Testing the UVC function
716 ------------------------
718 device: run the gadget, modprobe vivid
720 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
722 where uvc-gadget is this program:
723 http://git.ideasonboard.org/uvc-gadget.git
726 http://www.spinics.net/lists/linux-usb/msg99220.html
728 host: luvcview -f yuv
733 The function is provided by usb_f_printer.ko module.
735 Function-specific configfs interface
736 ------------------------------------
738 The function name to use when creating the function directory is "printer".
739 The printer function provides these attributes in its function directory:
741 pnp_string - Data to be passed to the host in pnp string
742 q_len - Number of requests per endpoint
744 Testing the PRINTER function
745 ----------------------------
747 The most basic testing:
749 device: run the gadget
750 # ls -l /devices/virtual/usb_printer_gadget/
752 should show g_printer<number>.
754 If udev is active, then /dev/g_printer<number> should appear automatically.
758 If udev is active, then e.g. /dev/usb/lp0 should appear.
760 host->device transmission:
763 # cat /dev/g_printer<number>
767 device->host transmission:
769 # cat > /dev/g_printer<number>
773 More advanced testing can be done with the prn_example
774 described in Documentation/usb/gadget-printer.txt.
777 20. UAC1 function (virtual ALSA card, using u_audio API)
780 The function is provided by usb_f_uac1.ko module.
781 It will create a virtual ALSA card and the audio streams are simply
782 sinked to and sourced from it.
784 Function-specific configfs interface
785 ------------------------------------
787 The function name to use when creating the function directory is "uac1".
788 The uac1 function provides these attributes in its function directory:
790 c_chmask - capture channel mask
791 c_srate - capture sampling rate
792 c_ssize - capture sample size (bytes)
793 p_chmask - playback channel mask
794 p_srate - playback sampling rate
795 p_ssize - playback sample size (bytes)
796 req_number - the number of pre-allocated request for both capture
799 The attributes have sane default values.
801 Testing the UAC1 function
802 -------------------------
804 device: run the gadget
805 host: aplay -l # should list our USB Audio Gadget
807 This function does not require real hardware support, it just
808 sends a stream of audio data to/from the host. In order to
809 actually hear something at the device side, a command similar
810 to this must be used at the device side:
812 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
816 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
817 aplay -D default:CARD=OdroidU3