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)
36 The function is provided by usb_f_acm.ko module.
38 Function-specific configfs interface
39 ------------------------------------
41 The function name to use when creating the function directory is "acm".
42 The ACM function provides just one attribute in its function directory:
46 The attribute is read-only.
48 There can be at most 4 ACM/generic serial/OBEX ports in the system.
51 Testing the ACM function
52 ------------------------
62 then the other way round
75 The function is provided by usb_f_ecm.ko module.
77 Function-specific configfs interface
78 ------------------------------------
80 The function name to use when creating the function directory is "ecm".
81 The ECM function provides these attributes in its function directory:
83 =============== ==================================================
84 ifname network device interface name associated with this
86 qmult queue length multiplier for high and super speed
87 host_addr MAC address of host's end of this
88 Ethernet over USB link
89 dev_addr MAC address of device's end of this
90 Ethernet over USB link
91 =============== ==================================================
93 and after creating the functions/ecm.<instance name> they contain default
94 values: qmult is 5, dev_addr and host_addr are randomly selected.
95 The ifname can be written to if the function is not bound. A write must be an
96 interface pattern such as "usb%d", which will cause the net core to choose the
97 next free usbX interface. By default, it is set to "usb%d".
99 Testing the ECM function
100 ------------------------
102 Configure IP addresses of the device and the host. Then:
112 3. ECM subset function
113 ======================
115 The function is provided by usb_f_ecm_subset.ko module.
117 Function-specific configfs interface
118 ------------------------------------
120 The function name to use when creating the function directory is "geth".
121 The ECM subset function provides these attributes in its function directory:
123 =============== ==================================================
124 ifname network device interface name associated with this
126 qmult queue length multiplier for high and super speed
127 host_addr MAC address of host's end of this
128 Ethernet over USB link
129 dev_addr MAC address of device's end of this
130 Ethernet over USB link
131 =============== ==================================================
133 and after creating the functions/ecm.<instance name> they contain default
134 values: qmult is 5, dev_addr and host_addr are randomly selected.
135 The ifname can be written to if the function is not bound. A write must be an
136 interface pattern such as "usb%d", which will cause the net core to choose the
137 next free usbX interface. By default, it is set to "usb%d".
139 Testing the ECM subset function
140 -------------------------------
142 Configure IP addresses of the device and the host. Then:
155 The function is provided by usb_f_eem.ko module.
157 Function-specific configfs interface
158 ------------------------------------
160 The function name to use when creating the function directory is "eem".
161 The EEM function provides these attributes in its function directory:
163 =============== ==================================================
164 ifname network device interface name associated with this
166 qmult queue length multiplier for high and super speed
167 host_addr MAC address of host's end of this
168 Ethernet over USB link
169 dev_addr MAC address of device's end of this
170 Ethernet over USB link
171 =============== ==================================================
173 and after creating the functions/eem.<instance name> they contain default
174 values: qmult is 5, dev_addr and host_addr are randomly selected.
175 The ifname can be written to if the function is not bound. A write must be an
176 interface pattern such as "usb%d", which will cause the net core to choose the
177 next free usbX interface. By default, it is set to "usb%d".
179 Testing the EEM function
180 ------------------------
182 Configure IP addresses of the device and the host. Then:
195 The function is provided by usb_f_fs.ko module.
197 Function-specific configfs interface
198 ------------------------------------
200 The function name to use when creating the function directory is "ffs".
201 The function directory is intentionally empty and not modifiable.
203 After creating the directory there is a new instance (a "device") of FunctionFS
204 available in the system. Once a "device" is available, the user should follow
205 the standard procedure for using FunctionFS (mount it, run the userspace
206 process which implements the function proper). The gadget should be enabled
207 by writing a suitable string to usb_gadget/<gadget>/UDC.
209 The FFS function provides just one attribute in its function directory:
213 The attribute is read-only and signals if the function is ready (1) to be
214 used, E.G. if userspace has written descriptors and strings to ep0, so
215 the gadget can be enabled.
217 Testing the FFS function
218 ------------------------
220 On the device: start the function's userspace daemon, enable the gadget
222 On the host: use the USB function provided by the device
227 The function is provided by usb_f_hid.ko module.
229 Function-specific configfs interface
230 ------------------------------------
232 The function name to use when creating the function directory is "hid".
233 The HID function provides these attributes in its function directory:
235 =============== ===========================================
236 protocol HID protocol to use
237 report_desc data to be used in HID reports, except data
238 passed with /dev/hidg<X>
239 report_length HID report length
240 subclass HID subclass to use
241 =============== ===========================================
243 For a keyboard the protocol and the subclass are 1, the report_length is 8,
244 while the report_desc is::
247 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.|
248 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.|
249 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....|
250 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...|
253 Such a sequence of bytes can be stored to the attribute with echo::
255 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
257 Testing the HID function
258 ------------------------
263 - connect the gadget to a host, preferably not the one used
264 to control the gadget
265 - run a program which writes to /dev/hidg<N>, e.g.
266 a userspace program found in Documentation/usb/gadget_hid.rst::
268 $ ./hid_gadget_test /dev/hidg0 keyboard
272 - observe the keystrokes from the gadget
277 The function is provided by usb_f_ss_lb.ko module.
279 Function-specific configfs interface
280 ------------------------------------
282 The function name to use when creating the function directory is "Loopback".
283 The LOOPBACK function provides these attributes in its function directory:
285 =============== =======================
286 qlen depth of loopback queue
287 bulk_buflen buffer length
288 =============== =======================
290 Testing the LOOPBACK function
291 -----------------------------
293 device: run the gadget
295 host: test-usb (tools/usb/testusb.c)
297 8. MASS STORAGE function
298 ========================
300 The function is provided by usb_f_mass_storage.ko module.
302 Function-specific configfs interface
303 ------------------------------------
305 The function name to use when creating the function directory is "mass_storage".
306 The MASS STORAGE function provides these attributes in its directory:
309 =============== ==============================================
310 stall Set to permit function to halt bulk endpoints.
311 Disabled on some USB devices known not to work
312 correctly. You should set it to true.
313 num_buffers Number of pipeline buffers. Valid numbers
314 are 2..4. Available only if
315 CONFIG_USB_GADGET_DEBUG_FILES is set.
316 =============== ==============================================
318 and a default lun.0 directory corresponding to SCSI LUN #0.
320 A new lun can be added with mkdir::
322 $ mkdir functions/mass_storage.0/partition.5
324 Lun numbering does not have to be continuous, except for lun #0 which is
325 created by default. A maximum of 8 luns can be specified and they all must be
326 named following the <name>.<number> scheme. The numbers can be 0..8.
327 Probably a good convention is to name the luns "lun.<number>",
328 although it is not mandatory.
330 In each lun directory there are the following attribute files:
332 =============== ==============================================
333 file The path to the backing file for the LUN.
334 Required if LUN is not marked as removable.
335 ro Flag specifying access to the LUN shall be
336 read-only. This is implied if CD-ROM emulation
337 is enabled as well as when it was impossible
338 to open "filename" in R/W mode.
339 removable Flag specifying that LUN shall be indicated as
341 cdrom Flag specifying that LUN shall be reported as
343 nofua Flag specifying that FUA flag
345 forced_eject This write-only file is useful only when
346 the function is active. It causes the backing
347 file to be forcibly detached from the LUN,
348 regardless of whether the host has allowed it.
349 Any non-zero number of bytes written will
351 =============== ==============================================
353 Testing the MASS STORAGE function
354 ---------------------------------
356 device: connect the gadget, enable it
357 host: dmesg, see the USB drives appear (if system configured to automatically
363 The function is provided by usb_f_midi.ko module.
365 Function-specific configfs interface
366 ------------------------------------
368 The function name to use when creating the function directory is "midi".
369 The MIDI function provides these attributes in its function directory:
371 =============== ====================================
372 buflen MIDI buffer length
373 id ID string for the USB MIDI adapter
374 in_ports number of MIDI input ports
375 index index value for the USB MIDI adapter
376 out_ports number of MIDI output ports
377 qlen USB read request queue length
378 =============== ====================================
380 Testing the MIDI function
381 -------------------------
383 There are two cases: playing a mid from the gadget to
384 the host and playing a mid from the host to the gadget.
386 1) Playing a mid from the gadget to the host:
391 Port Client name Port name
392 14:0 Midi Through Midi Through Port-0
393 24:0 MIDI Gadget MIDI Gadget MIDI 1
394 $ arecordmidi -p 24:0 from_gadget.mid
399 Port Client name Port name
402 $ aplaymidi -p 20:0 to_host.mid
404 2) Playing a mid from the host to the gadget
409 Port Client name Port name
412 $ arecordmidi -p 20:0 from_host.mid
417 Port Client name Port name
418 14:0 Midi Through Midi Through Port-0
419 24:0 MIDI Gadget MIDI Gadget MIDI 1
421 $ aplaymidi -p24:0 to_gadget.mid
423 The from_gadget.mid should sound identical to the to_host.mid.
425 The from_host.id should sound identical to the to_gadget.mid.
427 MIDI files can be played to speakers/headphones with e.g. timidity installed::
430 Port Client name Port name
431 14:0 Midi Through Midi Through Port-0
432 24:0 MIDI Gadget MIDI Gadget MIDI 1
433 128:0 TiMidity TiMidity port 0
434 128:1 TiMidity TiMidity port 1
435 128:2 TiMidity TiMidity port 2
436 128:3 TiMidity TiMidity port 3
438 $ aplaymidi -p 128:0 file.mid
440 MIDI ports can be logically connected using the aconnect utility, e.g.::
442 $ aconnect 24:0 128:0 # try it on the host
444 After the gadget's MIDI port is connected to timidity's MIDI port,
445 whatever is played at the gadget side with aplaymidi -l is audible
446 in host's speakers/headphones.
451 The function is provided by usb_f_ncm.ko module.
453 Function-specific configfs interface
454 ------------------------------------
456 The function name to use when creating the function directory is "ncm".
457 The NCM function provides these attributes in its function directory:
459 ======================= ==================================================
460 ifname network device interface name associated with this
462 qmult queue length multiplier for high and super speed
463 host_addr MAC address of host's end of this
464 Ethernet over USB link
465 dev_addr MAC address of device's end of this
466 Ethernet over USB link
467 max_segment_size Segment size required for P2P connections. This
468 will set MTU to 14 bytes
469 ======================= ==================================================
471 and after creating the functions/ncm.<instance name> they contain default
472 values: qmult is 5, dev_addr and host_addr are randomly selected.
473 The ifname can be written to if the function is not bound. A write must be an
474 interface pattern such as "usb%d", which will cause the net core to choose the
475 next free usbX interface. By default, it is set to "usb%d".
477 Testing the NCM function
478 ------------------------
480 Configure IP addresses of the device and the host. Then:
493 The function is provided by usb_f_obex.ko module.
495 Function-specific configfs interface
496 ------------------------------------
498 The function name to use when creating the function directory is "obex".
499 The OBEX function provides just one attribute in its function directory:
503 The attribute is read-only.
505 There can be at most 4 ACM/generic serial/OBEX ports in the system.
507 Testing the OBEX function
508 -------------------------
512 seriald -f /dev/ttyGS<Y> -s 1024
516 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
517 -t<out endpoint addr> -r<in endpoint addr>
519 where seriald and serialc are Felipe's utilities found here:
521 https://github.com/felipebalbi/usb-tools.git master
526 The function is provided by usb_f_phonet.ko module.
528 Function-specific configfs interface
529 ------------------------------------
531 The function name to use when creating the function directory is "phonet".
532 The PHONET function provides just one attribute in its function directory:
534 =============== ==================================================
535 ifname network device interface name associated with this
537 =============== ==================================================
539 Testing the PHONET function
540 ---------------------------
542 It is not possible to test the SOCK_STREAM protocol without a specific piece
543 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
544 in the past I had to apply the patch mentioned here:
546 http://www.spinics.net/lists/linux-usb/msg85689.html
548 These tools are required:
550 git://git.gitorious.org/meego-cellular/phonet-utils.git
554 $ ./phonet -a 0x10 -i usbpn0
555 $ ./pnroute add 0x6c usbpn0
556 $./pnroute add 0x10 usbpn0
561 $ ./phonet -a 0x6c -i upnlink0
562 $ ./pnroute add 0x10 upnlink0
563 $ ifconfig upnlink0 up
565 Then a test program can be used::
567 http://www.spinics.net/lists/linux-usb/msg85690.html
571 $ ./pnxmit -a 0x6c -r
575 $ ./pnxmit -a 0x10 -s 0x6c
577 As a result some data should be sent from host to device.
578 Then the other way round:
582 $ ./pnxmit -a 0x10 -r
586 $ ./pnxmit -a 0x6c -s 0x10
591 The function is provided by usb_f_rndis.ko module.
593 Function-specific configfs interface
594 ------------------------------------
596 The function name to use when creating the function directory is "rndis".
597 The RNDIS function provides these attributes in its function directory:
599 =============== ==================================================
600 ifname network device interface name associated with this
602 qmult queue length multiplier for high and super speed
603 host_addr MAC address of host's end of this
604 Ethernet over USB link
605 dev_addr MAC address of device's end of this
606 Ethernet over USB link
607 =============== ==================================================
609 and after creating the functions/rndis.<instance name> they contain default
610 values: qmult is 5, dev_addr and host_addr are randomly selected.
611 The ifname can be written to if the function is not bound. A write must be an
612 interface pattern such as "usb%d", which will cause the net core to choose the
613 next free usbX interface. By default, it is set to "usb%d".
615 Testing the RNDIS function
616 --------------------------
618 Configure IP addresses of the device and the host. Then:
631 The function is provided by usb_f_gser.ko module.
633 Function-specific configfs interface
634 ------------------------------------
636 The function name to use when creating the function directory is "gser".
637 The SERIAL function provides just one attribute in its function directory:
641 The attribute is read-only.
643 There can be at most 4 ACM/generic serial/OBEX ports in the system.
645 Testing the SERIAL function
646 ---------------------------
651 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
661 then the other way round
671 15. SOURCESINK function
672 =======================
674 The function is provided by usb_f_ss_lb.ko module.
676 Function-specific configfs interface
677 ------------------------------------
679 The function name to use when creating the function directory is "SourceSink".
680 The SOURCESINK function provides these attributes in its function directory:
682 =============== ==================================
683 pattern 0 (all zeros), 1 (mod63), 2 (none)
685 isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss)
686 isoc_mult 0..2 (hs/ss only)
687 isoc_maxburst 0..15 (ss only)
688 bulk_buflen buffer length
689 bulk_qlen depth of queue for bulk
690 iso_qlen depth of queue for iso
691 =============== ==================================
693 Testing the SOURCESINK function
694 -------------------------------
696 device: run the gadget
698 host: test-usb (tools/usb/testusb.c)
701 16. UAC1 function (legacy implementation)
702 =========================================
704 The function is provided by usb_f_uac1_legacy.ko module.
706 Function-specific configfs interface
707 ------------------------------------
709 The function name to use when creating the function directory
711 The uac1 function provides these attributes in its function directory:
713 =============== ====================================
714 audio_buf_size audio buffer size
715 fn_cap capture pcm device file name
716 fn_cntl control device file name
717 fn_play playback pcm device file name
718 req_buf_size ISO OUT endpoint request buffer size
719 req_count ISO OUT endpoint request count
720 =============== ====================================
722 The attributes have sane default values.
724 Testing the UAC1 function
725 -------------------------
727 device: run the gadget
731 aplay -l # should list our USB Audio Gadget
736 The function is provided by usb_f_uac2.ko module.
738 Function-specific configfs interface
739 ------------------------------------
741 The function name to use when creating the function directory is "uac2".
742 The uac2 function provides these attributes in its function directory:
744 ================ ====================================================
745 c_chmask capture channel mask
746 c_srate list of capture sampling rates (comma-separated)
747 c_ssize capture sample size (bytes)
748 c_sync capture synchronization type (async/adaptive)
749 c_mute_present capture mute control enable
750 c_volume_present capture volume control enable
751 c_volume_min capture volume control min value (in 1/256 dB)
752 c_volume_max capture volume control max value (in 1/256 dB)
753 c_volume_res capture volume control resolution (in 1/256 dB)
754 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto)
755 fb_max maximum extra bandwidth in async mode
756 p_chmask playback channel mask
757 p_srate list of playback sampling rates (comma-separated)
758 p_ssize playback sample size (bytes)
759 p_mute_present playback mute control enable
760 p_volume_present playback volume control enable
761 p_volume_min playback volume control min value (in 1/256 dB)
762 p_volume_max playback volume control max value (in 1/256 dB)
763 p_volume_res playback volume control resolution (in 1/256 dB)
764 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto)
765 req_number the number of pre-allocated request for both capture
767 function_name name of the interface
768 c_terminal_type code of the capture terminal type
769 p_terminal_type code of the playback terminal type
770 ================ ====================================================
772 The attributes have sane default values.
774 Testing the UAC2 function
775 -------------------------
777 device: run the gadget
778 host: aplay -l # should list our USB Audio Gadget
780 This function does not require real hardware support, it just
781 sends a stream of audio data to/from the host. In order to
782 actually hear something at the device side, a command similar
783 to this must be used at the device side::
785 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
789 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
790 aplay -D default:CARD=OdroidU3
795 The function is provided by usb_f_uvc.ko module.
797 Function-specific configfs interface
798 ------------------------------------
800 The function name to use when creating the function directory is "uvc".
801 The uvc function provides these attributes in its function directory:
803 =================== ================================================
804 streaming_interval interval for polling endpoint for data transfers
805 streaming_maxburst bMaxBurst for super speed companion descriptor
806 streaming_maxpacket maximum packet size this endpoint is capable of
807 sending or receiving when this configuration is
809 function_name name of the interface
810 =================== ================================================
812 There are also "control" and "streaming" subdirectories, each of which contain
813 a number of their subdirectories. There are some sane defaults provided, but
814 the user must provide the following:
816 ================== ====================================================
817 control header create in control/header, link from control/class/fs
818 and/or control/class/ss
819 streaming header create in streaming/header, link from
820 streaming/class/fs and/or streaming/class/hs and/or
822 format description create in streaming/mjpeg and/or
823 streaming/uncompressed
824 frame description create in streaming/mjpeg/<format> and/or in
825 streaming/uncompressed/<format>
826 ================== ====================================================
828 Each frame description contains frame interval specification, and each
829 such specification consists of a number of lines with an interval value
830 in each line. The rules stated above are best illustrated with an example::
832 # mkdir functions/uvc.usb0/control/header/h
833 # cd functions/uvc.usb0/control/
834 # ln -s header/h class/fs
835 # ln -s header/h class/ss
836 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
837 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
842 # cd $GADGET_CONFIGFS_ROOT
843 # mkdir functions/uvc.usb0/streaming/header/h
844 # cd functions/uvc.usb0/streaming/header/h
845 # ln -s ../../uncompressed/u
847 # ln -s ../../header/h
849 # ln -s ../../header/h
851 # ln -s ../../header/h
854 Testing the UVC function
855 ------------------------
857 device: run the gadget, modprobe vivid::
859 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
861 where uvc-gadget is this program:
862 http://git.ideasonboard.org/uvc-gadget.git
866 http://www.spinics.net/lists/linux-usb/msg99220.html
875 The function is provided by usb_f_printer.ko module.
877 Function-specific configfs interface
878 ------------------------------------
880 The function name to use when creating the function directory is "printer".
881 The printer function provides these attributes in its function directory:
883 ========== ===========================================
884 pnp_string Data to be passed to the host in pnp string
885 q_len Number of requests per endpoint
886 ========== ===========================================
888 Testing the PRINTER function
889 ----------------------------
891 The most basic testing:
893 device: run the gadget::
895 # ls -l /devices/virtual/usb_printer_gadget/
897 should show g_printer<number>.
899 If udev is active, then /dev/g_printer<number> should appear automatically.
903 If udev is active, then e.g. /dev/usb/lp0 should appear.
905 host->device transmission:
909 # cat /dev/g_printer<number>
915 device->host transmission::
917 # cat > /dev/g_printer<number>
923 More advanced testing can be done with the prn_example
924 described in Documentation/usb/gadget_printer.rst.
927 20. UAC1 function (virtual ALSA card, using u_audio API)
928 ========================================================
930 The function is provided by usb_f_uac1.ko module.
931 It will create a virtual ALSA card and the audio streams are simply
932 sinked to and sourced from it.
934 Function-specific configfs interface
935 ------------------------------------
937 The function name to use when creating the function directory is "uac1".
938 The uac1 function provides these attributes in its function directory:
940 ================ ====================================================
941 c_chmask capture channel mask
942 c_srate list of capture sampling rates (comma-separated)
943 c_ssize capture sample size (bytes)
944 c_mute_present capture mute control enable
945 c_volume_present capture volume control enable
946 c_volume_min capture volume control min value (in 1/256 dB)
947 c_volume_max capture volume control max value (in 1/256 dB)
948 c_volume_res capture volume control resolution (in 1/256 dB)
949 p_chmask playback channel mask
950 p_srate list of playback sampling rates (comma-separated)
951 p_ssize playback sample size (bytes)
952 p_mute_present playback mute control enable
953 p_volume_present playback volume control enable
954 p_volume_min playback volume control min value (in 1/256 dB)
955 p_volume_max playback volume control max value (in 1/256 dB)
956 p_volume_res playback volume control resolution (in 1/256 dB)
957 req_number the number of pre-allocated requests for both capture
959 function_name name of the interface
960 ================ ====================================================
962 The attributes have sane default values.
964 Testing the UAC1 function
965 -------------------------
967 device: run the gadget
968 host: aplay -l # should list our USB Audio Gadget
970 This function does not require real hardware support, it just
971 sends a stream of audio data to/from the host. In order to
972 actually hear something at the device side, a command similar
973 to this must be used at the device side::
975 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
979 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
980 aplay -D default:CARD=OdroidU3
986 The function is provided by usb_f_midi2.ko module.
987 It will create a virtual ALSA card containing a UMP rawmidi device
988 where the UMP packet is looped back. In addition, a legacy rawmidi
989 device is created. The UMP rawmidi is bound with ALSA sequencer
992 Function-specific configfs interface
993 ------------------------------------
995 The function name to use when creating the function directory is "midi2".
996 The midi2 function provides these attributes in its function directory
997 as the card top-level information:
999 ============= =================================================
1000 process_ump Bool flag to process UMP Stream messages (0 or 1)
1001 static_block Bool flag for static blocks (0 or 1)
1002 iface_name Optional interface name string
1003 ============= =================================================
1005 The directory contains a subdirectory "ep.0", and this provides the
1006 attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):
1008 ============= =================================================
1009 protocol_caps MIDI protocol capabilities;
1010 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
1011 protocol Default MIDI protocol (either 1 or 2)
1012 ep_name UMP Endpoint name string
1013 product_id Product ID string
1014 manufacturer Manufacture ID number (24 bit)
1015 family Device family ID number (16 bit)
1016 model Device model ID number (16 bit)
1017 sw_revision Software revision (32 bit)
1018 ============= =================================================
1020 Each Endpoint subdirectory contains a subdirectory "block.0", which
1021 represents the Function Block for Block 0 information.
1024 ================= ===============================================
1025 name Function Block name string
1026 direction Direction of this FB
1027 1: input, 2: output, or 3: bidirectional
1028 first_group The first UMP Group number (0-15)
1029 num_groups The number of groups in this FB (1-16)
1030 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15)
1031 midi1_num_groups The number of groups for MIDI 1.0 (0-16)
1032 ui_hint UI-hint of this FB
1033 0: unknown, 1: receiver, 2: sender, 3: both
1034 midi_ci_verison Supported MIDI-CI version number (8 bit)
1035 is_midi1 Legacy MIDI 1.0 device (0-2)
1037 1: MIDI 1.0 without restriction, or
1038 2: MIDI 1.0 with low speed
1039 sysex8_streams Max number of SysEx8 streams (8 bit)
1040 active Bool flag for FB activity (0 or 1)
1041 ================= ===============================================
1043 If multiple Function Blocks are required, you can add more Function
1044 Blocks by creating subdirectories "block.<num>" with the corresponding
1045 Function Block number (1, 2, ....). The FB subdirectories can be
1046 dynamically removed, too. Note that the Function Block numbers must be
1049 Similarly, if you multiple UMP Endpoints are required, you can add
1050 more Endpoints by creating subdirectories "ep.<num>". The number must
1053 For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1054 to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1056 Testing the MIDI2 function
1057 --------------------------
1059 On the device: run the gadget, and running::
1061 $ cat /proc/asound/cards
1063 will show a new sound card containing a MIDI2 device.
1067 $ cat /proc/asound/cards
1069 will show a new sound card containing either MIDI1 or MIDI2 device,
1070 depending on the USB audio driver configuration.
1072 On both, when ALSA sequencer is enabled on the host, you can find the
1073 UMP MIDI client such as "MIDI 2.0 Gadget".
1075 As the driver simply loops back the data, there is no need for a real
1076 device just for testing.
1078 For testing a MIDI input from the gadget to the host (e.g. emulating a
1079 MIDI keyboard), you can send a MIDI stream like the following.
1085 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
1087 1 'Group 1 (MIDI 2.0 Gadget I/O)'
1088 $ aplaymidi -p 20:1 to_host.mid
1094 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
1096 1 'Group 1 (MIDI 2.0 Gadget I/O)'
1097 $ arecordmidi -p 24:1 from_gadget.mid
1099 If you have a UMP-capable application, you can use the UMP port to
1100 send/receive the raw UMP packets, too. For example, aseqdump program
1101 with UMP support can receive from UMP port. On the host::
1103 $ aseqdump -u 2 -p 24:1
1104 Waiting for data. Press Ctrl+C to end.
1105 Source Group Event Ch Data
1106 24:1 Group 0, Program change 0, program 0, Bank select 0:0
1107 24:1 Group 0, Channel pressure 0, value 0x80000000
1109 For testing a MIDI output to the gadget to the host (e.g. emulating a
1110 MIDI synth), it'll be just other way round.
1114 $ arecordmidi -p 20:1 from_host.mid
1118 $ aplaymidi -p 24:1 to_gadget.mid
1120 The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1121 translated from/to UMP packets on the gadget. It's bound to only
1124 The current operation mode can be observed in ALSA control element
1125 "Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example::
1127 $ amixer -c1 contents
1128 numid=1,iface=RAWMIDI,name='Operation Mode'
1129 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
1132 where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1133 The example above shows it's running in 2, i.e. MIDI 2.0.