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 Testing the FFS function
210 ------------------------
212 On the device: start the function's userspace daemon, enable the gadget
214 On the host: use the USB function provided by the device
219 The function is provided by usb_f_hid.ko module.
221 Function-specific configfs interface
222 ------------------------------------
224 The function name to use when creating the function directory is "hid".
225 The HID function provides these attributes in its function directory:
227 =============== ===========================================
228 protocol HID protocol to use
229 report_desc data to be used in HID reports, except data
230 passed with /dev/hidg<X>
231 report_length HID report length
232 subclass HID subclass to use
233 =============== ===========================================
235 For a keyboard the protocol and the subclass are 1, the report_length is 8,
236 while the report_desc is::
239 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.|
240 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.|
241 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....|
242 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...|
245 Such a sequence of bytes can be stored to the attribute with echo::
247 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
249 Testing the HID function
250 ------------------------
255 - connect the gadget to a host, preferably not the one used
256 to control the gadget
257 - run a program which writes to /dev/hidg<N>, e.g.
258 a userspace program found in Documentation/usb/gadget_hid.rst::
260 $ ./hid_gadget_test /dev/hidg0 keyboard
264 - observe the keystrokes from the gadget
269 The function is provided by usb_f_ss_lb.ko module.
271 Function-specific configfs interface
272 ------------------------------------
274 The function name to use when creating the function directory is "Loopback".
275 The LOOPBACK function provides these attributes in its function directory:
277 =============== =======================
278 qlen depth of loopback queue
279 bulk_buflen buffer length
280 =============== =======================
282 Testing the LOOPBACK function
283 -----------------------------
285 device: run the gadget
287 host: test-usb (tools/usb/testusb.c)
289 8. MASS STORAGE function
290 ========================
292 The function is provided by usb_f_mass_storage.ko module.
294 Function-specific configfs interface
295 ------------------------------------
297 The function name to use when creating the function directory is "mass_storage".
298 The MASS STORAGE function provides these attributes in its directory:
301 =============== ==============================================
302 stall Set to permit function to halt bulk endpoints.
303 Disabled on some USB devices known not to work
304 correctly. You should set it to true.
305 num_buffers Number of pipeline buffers. Valid numbers
306 are 2..4. Available only if
307 CONFIG_USB_GADGET_DEBUG_FILES is set.
308 =============== ==============================================
310 and a default lun.0 directory corresponding to SCSI LUN #0.
312 A new lun can be added with mkdir::
314 $ mkdir functions/mass_storage.0/partition.5
316 Lun numbering does not have to be continuous, except for lun #0 which is
317 created by default. A maximum of 8 luns can be specified and they all must be
318 named following the <name>.<number> scheme. The numbers can be 0..8.
319 Probably a good convention is to name the luns "lun.<number>",
320 although it is not mandatory.
322 In each lun directory there are the following attribute files:
324 =============== ==============================================
325 file The path to the backing file for the LUN.
326 Required if LUN is not marked as removable.
327 ro Flag specifying access to the LUN shall be
328 read-only. This is implied if CD-ROM emulation
329 is enabled as well as when it was impossible
330 to open "filename" in R/W mode.
331 removable Flag specifying that LUN shall be indicated as
333 cdrom Flag specifying that LUN shall be reported as
335 nofua Flag specifying that FUA flag
337 forced_eject This write-only file is useful only when
338 the function is active. It causes the backing
339 file to be forcibly detached from the LUN,
340 regardless of whether the host has allowed it.
341 Any non-zero number of bytes written will
343 =============== ==============================================
345 Testing the MASS STORAGE function
346 ---------------------------------
348 device: connect the gadget, enable it
349 host: dmesg, see the USB drives appear (if system configured to automatically
355 The function is provided by usb_f_midi.ko module.
357 Function-specific configfs interface
358 ------------------------------------
360 The function name to use when creating the function directory is "midi".
361 The MIDI function provides these attributes in its function directory:
363 =============== ====================================
364 buflen MIDI buffer length
365 id ID string for the USB MIDI adapter
366 in_ports number of MIDI input ports
367 index index value for the USB MIDI adapter
368 out_ports number of MIDI output ports
369 qlen USB read request queue length
370 =============== ====================================
372 Testing the MIDI function
373 -------------------------
375 There are two cases: playing a mid from the gadget to
376 the host and playing a mid from the host to the gadget.
378 1) Playing a mid from the gadget to the host:
383 Port Client name Port name
384 14:0 Midi Through Midi Through Port-0
385 24:0 MIDI Gadget MIDI Gadget MIDI 1
386 $ arecordmidi -p 24:0 from_gadget.mid
391 Port Client name Port name
394 $ aplaymidi -p 20:0 to_host.mid
396 2) Playing a mid from the host to the gadget
401 Port Client name Port name
404 $ arecordmidi -p 20:0 from_host.mid
409 Port Client name Port name
410 14:0 Midi Through Midi Through Port-0
411 24:0 MIDI Gadget MIDI Gadget MIDI 1
413 $ aplaymidi -p24:0 to_gadget.mid
415 The from_gadget.mid should sound identical to the to_host.mid.
417 The from_host.id should sound identical to the to_gadget.mid.
419 MIDI files can be played to speakers/headphones with e.g. timidity installed::
422 Port Client name Port name
423 14:0 Midi Through Midi Through Port-0
424 24:0 MIDI Gadget MIDI Gadget MIDI 1
425 128:0 TiMidity TiMidity port 0
426 128:1 TiMidity TiMidity port 1
427 128:2 TiMidity TiMidity port 2
428 128:3 TiMidity TiMidity port 3
430 $ aplaymidi -p 128:0 file.mid
432 MIDI ports can be logically connected using the aconnect utility, e.g.::
434 $ aconnect 24:0 128:0 # try it on the host
436 After the gadget's MIDI port is connected to timidity's MIDI port,
437 whatever is played at the gadget side with aplaymidi -l is audible
438 in host's speakers/headphones.
443 The function is provided by usb_f_ncm.ko module.
445 Function-specific configfs interface
446 ------------------------------------
448 The function name to use when creating the function directory is "ncm".
449 The NCM function provides these attributes in its function directory:
451 =============== ==================================================
452 ifname network device interface name associated with this
454 qmult queue length multiplier for high and super speed
455 host_addr MAC address of host's end of this
456 Ethernet over USB link
457 dev_addr MAC address of device's end of this
458 Ethernet over USB link
459 =============== ==================================================
461 and after creating the functions/ncm.<instance name> they contain default
462 values: qmult is 5, dev_addr and host_addr are randomly selected.
463 The ifname can be written to if the function is not bound. A write must be an
464 interface pattern such as "usb%d", which will cause the net core to choose the
465 next free usbX interface. By default, it is set to "usb%d".
467 Testing the NCM function
468 ------------------------
470 Configure IP addresses of the device and the host. Then:
483 The function is provided by usb_f_obex.ko module.
485 Function-specific configfs interface
486 ------------------------------------
488 The function name to use when creating the function directory is "obex".
489 The OBEX function provides just one attribute in its function directory:
493 The attribute is read-only.
495 There can be at most 4 ACM/generic serial/OBEX ports in the system.
497 Testing the OBEX function
498 -------------------------
502 seriald -f /dev/ttyGS<Y> -s 1024
506 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
507 -t<out endpoint addr> -r<in endpoint addr>
509 where seriald and serialc are Felipe's utilities found here:
511 https://github.com/felipebalbi/usb-tools.git master
516 The function is provided by usb_f_phonet.ko module.
518 Function-specific configfs interface
519 ------------------------------------
521 The function name to use when creating the function directory is "phonet".
522 The PHONET function provides just one attribute in its function directory:
524 =============== ==================================================
525 ifname network device interface name associated with this
527 =============== ==================================================
529 Testing the PHONET function
530 ---------------------------
532 It is not possible to test the SOCK_STREAM protocol without a specific piece
533 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
534 in the past I had to apply the patch mentioned here:
536 http://www.spinics.net/lists/linux-usb/msg85689.html
538 These tools are required:
540 git://git.gitorious.org/meego-cellular/phonet-utils.git
544 $ ./phonet -a 0x10 -i usbpn0
545 $ ./pnroute add 0x6c usbpn0
546 $./pnroute add 0x10 usbpn0
551 $ ./phonet -a 0x6c -i upnlink0
552 $ ./pnroute add 0x10 upnlink0
553 $ ifconfig upnlink0 up
555 Then a test program can be used::
557 http://www.spinics.net/lists/linux-usb/msg85690.html
561 $ ./pnxmit -a 0x6c -r
565 $ ./pnxmit -a 0x10 -s 0x6c
567 As a result some data should be sent from host to device.
568 Then the other way round:
572 $ ./pnxmit -a 0x10 -r
576 $ ./pnxmit -a 0x6c -s 0x10
581 The function is provided by usb_f_rndis.ko module.
583 Function-specific configfs interface
584 ------------------------------------
586 The function name to use when creating the function directory is "rndis".
587 The RNDIS function provides these attributes in its function directory:
589 =============== ==================================================
590 ifname network device interface name associated with this
592 qmult queue length multiplier for high and super speed
593 host_addr MAC address of host's end of this
594 Ethernet over USB link
595 dev_addr MAC address of device's end of this
596 Ethernet over USB link
597 =============== ==================================================
599 and after creating the functions/rndis.<instance name> they contain default
600 values: qmult is 5, dev_addr and host_addr are randomly selected.
601 The ifname can be written to if the function is not bound. A write must be an
602 interface pattern such as "usb%d", which will cause the net core to choose the
603 next free usbX interface. By default, it is set to "usb%d".
605 Testing the RNDIS function
606 --------------------------
608 Configure IP addresses of the device and the host. Then:
621 The function is provided by usb_f_gser.ko module.
623 Function-specific configfs interface
624 ------------------------------------
626 The function name to use when creating the function directory is "gser".
627 The SERIAL function provides just one attribute in its function directory:
631 The attribute is read-only.
633 There can be at most 4 ACM/generic serial/OBEX ports in the system.
635 Testing the SERIAL function
636 ---------------------------
641 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
651 then the other way round
661 15. SOURCESINK function
662 =======================
664 The function is provided by usb_f_ss_lb.ko module.
666 Function-specific configfs interface
667 ------------------------------------
669 The function name to use when creating the function directory is "SourceSink".
670 The SOURCESINK function provides these attributes in its function directory:
672 =============== ==================================
673 pattern 0 (all zeros), 1 (mod63), 2 (none)
675 isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss)
676 isoc_mult 0..2 (hs/ss only)
677 isoc_maxburst 0..15 (ss only)
678 bulk_buflen buffer length
679 bulk_qlen depth of queue for bulk
680 iso_qlen depth of queue for iso
681 =============== ==================================
683 Testing the SOURCESINK function
684 -------------------------------
686 device: run the gadget
688 host: test-usb (tools/usb/testusb.c)
691 16. UAC1 function (legacy implementation)
692 =========================================
694 The function is provided by usb_f_uac1_legacy.ko module.
696 Function-specific configfs interface
697 ------------------------------------
699 The function name to use when creating the function directory
701 The uac1 function provides these attributes in its function directory:
703 =============== ====================================
704 audio_buf_size audio buffer size
705 fn_cap capture pcm device file name
706 fn_cntl control device file name
707 fn_play playback pcm device file name
708 req_buf_size ISO OUT endpoint request buffer size
709 req_count ISO OUT endpoint request count
710 =============== ====================================
712 The attributes have sane default values.
714 Testing the UAC1 function
715 -------------------------
717 device: run the gadget
721 aplay -l # should list our USB Audio Gadget
726 The function is provided by usb_f_uac2.ko module.
728 Function-specific configfs interface
729 ------------------------------------
731 The function name to use when creating the function directory is "uac2".
732 The uac2 function provides these attributes in its function directory:
734 ================ ====================================================
735 c_chmask capture channel mask
736 c_srate list of capture sampling rates (comma-separated)
737 c_ssize capture sample size (bytes)
738 c_sync capture synchronization type (async/adaptive)
739 c_mute_present capture mute control enable
740 c_volume_present capture volume control enable
741 c_volume_min capture volume control min value (in 1/256 dB)
742 c_volume_max capture volume control max value (in 1/256 dB)
743 c_volume_res capture volume control resolution (in 1/256 dB)
744 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto)
745 fb_max maximum extra bandwidth in async mode
746 p_chmask playback channel mask
747 p_srate list of playback sampling rates (comma-separated)
748 p_ssize playback sample size (bytes)
749 p_mute_present playback mute control enable
750 p_volume_present playback volume control enable
751 p_volume_min playback volume control min value (in 1/256 dB)
752 p_volume_max playback volume control max value (in 1/256 dB)
753 p_volume_res playback volume control resolution (in 1/256 dB)
754 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto)
755 req_number the number of pre-allocated request for both capture
757 function_name name of the interface
758 c_terminal_type code of the capture terminal type
759 p_terminal_type code of the playback terminal type
760 ================ ====================================================
762 The attributes have sane default values.
764 Testing the UAC2 function
765 -------------------------
767 device: run the gadget
768 host: aplay -l # should list our USB Audio Gadget
770 This function does not require real hardware support, it just
771 sends a stream of audio data to/from the host. In order to
772 actually hear something at the device side, a command similar
773 to this must be used at the device side::
775 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
779 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
780 aplay -D default:CARD=OdroidU3
785 The function is provided by usb_f_uvc.ko module.
787 Function-specific configfs interface
788 ------------------------------------
790 The function name to use when creating the function directory is "uvc".
791 The uvc function provides these attributes in its function directory:
793 =================== ================================================
794 streaming_interval interval for polling endpoint for data transfers
795 streaming_maxburst bMaxBurst for super speed companion descriptor
796 streaming_maxpacket maximum packet size this endpoint is capable of
797 sending or receiving when this configuration is
799 function_name name of the interface
800 =================== ================================================
802 There are also "control" and "streaming" subdirectories, each of which contain
803 a number of their subdirectories. There are some sane defaults provided, but
804 the user must provide the following:
806 ================== ====================================================
807 control header create in control/header, link from control/class/fs
808 and/or control/class/ss
809 streaming header create in streaming/header, link from
810 streaming/class/fs and/or streaming/class/hs and/or
812 format description create in streaming/mjpeg and/or
813 streaming/uncompressed
814 frame description create in streaming/mjpeg/<format> and/or in
815 streaming/uncompressed/<format>
816 ================== ====================================================
818 Each frame description contains frame interval specification, and each
819 such specification consists of a number of lines with an interval value
820 in each line. The rules stated above are best illustrated with an example::
822 # mkdir functions/uvc.usb0/control/header/h
823 # cd functions/uvc.usb0/control/
824 # ln -s header/h class/fs
825 # ln -s header/h class/ss
826 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
827 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
832 # cd $GADGET_CONFIGFS_ROOT
833 # mkdir functions/uvc.usb0/streaming/header/h
834 # cd functions/uvc.usb0/streaming/header/h
835 # ln -s ../../uncompressed/u
837 # ln -s ../../header/h
839 # ln -s ../../header/h
841 # ln -s ../../header/h
844 Testing the UVC function
845 ------------------------
847 device: run the gadget, modprobe vivid::
849 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
851 where uvc-gadget is this program:
852 http://git.ideasonboard.org/uvc-gadget.git
856 http://www.spinics.net/lists/linux-usb/msg99220.html
865 The function is provided by usb_f_printer.ko module.
867 Function-specific configfs interface
868 ------------------------------------
870 The function name to use when creating the function directory is "printer".
871 The printer function provides these attributes in its function directory:
873 ========== ===========================================
874 pnp_string Data to be passed to the host in pnp string
875 q_len Number of requests per endpoint
876 ========== ===========================================
878 Testing the PRINTER function
879 ----------------------------
881 The most basic testing:
883 device: run the gadget::
885 # ls -l /devices/virtual/usb_printer_gadget/
887 should show g_printer<number>.
889 If udev is active, then /dev/g_printer<number> should appear automatically.
893 If udev is active, then e.g. /dev/usb/lp0 should appear.
895 host->device transmission:
899 # cat /dev/g_printer<number>
905 device->host transmission::
907 # cat > /dev/g_printer<number>
913 More advanced testing can be done with the prn_example
914 described in Documentation/usb/gadget_printer.rst.
917 20. UAC1 function (virtual ALSA card, using u_audio API)
918 ========================================================
920 The function is provided by usb_f_uac1.ko module.
921 It will create a virtual ALSA card and the audio streams are simply
922 sinked to and sourced from it.
924 Function-specific configfs interface
925 ------------------------------------
927 The function name to use when creating the function directory is "uac1".
928 The uac1 function provides these attributes in its function directory:
930 ================ ====================================================
931 c_chmask capture channel mask
932 c_srate list of capture sampling rates (comma-separated)
933 c_ssize capture sample size (bytes)
934 c_mute_present capture mute control enable
935 c_volume_present capture volume control enable
936 c_volume_min capture volume control min value (in 1/256 dB)
937 c_volume_max capture volume control max value (in 1/256 dB)
938 c_volume_res capture volume control resolution (in 1/256 dB)
939 p_chmask playback channel mask
940 p_srate list of playback sampling rates (comma-separated)
941 p_ssize playback sample size (bytes)
942 p_mute_present playback mute control enable
943 p_volume_present playback volume control enable
944 p_volume_min playback volume control min value (in 1/256 dB)
945 p_volume_max playback volume control max value (in 1/256 dB)
946 p_volume_res playback volume control resolution (in 1/256 dB)
947 req_number the number of pre-allocated requests for both capture
949 function_name name of the interface
950 ================ ====================================================
952 The attributes have sane default values.
954 Testing the UAC1 function
955 -------------------------
957 device: run the gadget
958 host: aplay -l # should list our USB Audio Gadget
960 This function does not require real hardware support, it just
961 sends a stream of audio data to/from the host. In order to
962 actually hear something at the device side, a command similar
963 to this must be used at the device side::
965 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
969 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
970 aplay -D default:CARD=OdroidU3
976 The function is provided by usb_f_midi2.ko module.
977 It will create a virtual ALSA card containing a UMP rawmidi device
978 where the UMP packet is looped back. In addition, a legacy rawmidi
979 device is created. The UMP rawmidi is bound with ALSA sequencer
982 Function-specific configfs interface
983 ------------------------------------
985 The function name to use when creating the function directory is "midi2".
986 The midi2 function provides these attributes in its function directory
987 as the card top-level information:
989 ============= =================================================
990 process_ump Bool flag to process UMP Stream messages (0 or 1)
991 static_block Bool flag for static blocks (0 or 1)
992 iface_name Optional interface name string
993 ============= =================================================
995 The directory contains a subdirectory "ep.0", and this provides the
996 attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):
998 ============= =================================================
999 protocol_caps MIDI protocol capabilities;
1000 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
1001 protocol Default MIDI protocol (either 1 or 2)
1002 ep_name UMP Endpoint name string
1003 product_id Product ID string
1004 manufacturer Manufacture ID number (24 bit)
1005 family Device family ID number (16 bit)
1006 model Device model ID number (16 bit)
1007 sw_revision Software revision (32 bit)
1008 ============= =================================================
1010 Each Endpoint subdirectory contains a subdirectory "block.0", which
1011 represents the Function Block for Block 0 information.
1014 ================= ===============================================
1015 name Function Block name string
1016 direction Direction of this FB
1017 1: input, 2: output, or 3: bidirectional
1018 first_group The first UMP Group number (0-15)
1019 num_groups The number of groups in this FB (1-16)
1020 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15)
1021 midi1_num_groups The number of groups for MIDI 1.0 (0-16)
1022 ui_hint UI-hint of this FB
1023 0: unknown, 1: receiver, 2: sender, 3: both
1024 midi_ci_verison Supported MIDI-CI version number (8 bit)
1025 is_midi1 Legacy MIDI 1.0 device (0-2)
1027 1: MIDI 1.0 without restriction, or
1028 2: MIDI 1.0 with low speed
1029 sysex8_streams Max number of SysEx8 streams (8 bit)
1030 active Bool flag for FB activity (0 or 1)
1031 ================= ===============================================
1033 If multiple Function Blocks are required, you can add more Function
1034 Blocks by creating subdirectories "block.<num>" with the corresponding
1035 Function Block number (1, 2, ....). The FB subdirectories can be
1036 dynamically removed, too. Note that the Function Block numbers must be
1039 Similarly, if you multiple UMP Endpoints are required, you can add
1040 more Endpoints by creating subdirectories "ep.<num>". The number must
1043 For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1044 to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1046 Testing the MIDI2 function
1047 --------------------------
1049 On the device: run the gadget, and running::
1051 $ cat /proc/asound/cards
1053 will show a new sound card containing a MIDI2 device.
1057 $ cat /proc/asound/cards
1059 will show a new sound card containing either MIDI1 or MIDI2 device,
1060 depending on the USB audio driver configuration.
1062 On both, when ALSA sequencer is enabled on the host, you can find the
1063 UMP MIDI client such as "MIDI 2.0 Gadget".
1065 As the driver simply loops back the data, there is no need for a real
1066 device just for testing.
1068 For testing a MIDI input from the gadget to the host (e.g. emulating a
1069 MIDI keyboard), you can send a MIDI stream like the following.
1075 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
1077 1 'Group 1 (MIDI 2.0 Gadget I/O)'
1078 $ aplaymidi -p 20:1 to_host.mid
1084 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
1086 1 'Group 1 (MIDI 2.0 Gadget I/O)'
1087 $ arecordmidi -p 24:1 from_gadget.mid
1089 If you have a UMP-capable application, you can use the UMP port to
1090 send/receive the raw UMP packets, too. For example, aseqdump program
1091 with UMP support can receive from UMP port. On the host::
1093 $ aseqdump -u 2 -p 24:1
1094 Waiting for data. Press Ctrl+C to end.
1095 Source Group Event Ch Data
1096 24:1 Group 0, Program change 0, program 0, Bank select 0:0
1097 24:1 Group 0, Channel pressure 0, value 0x80000000
1099 For testing a MIDI output to the gadget to the host (e.g. emulating a
1100 MIDI synth), it'll be just other way round.
1104 $ arecordmidi -p 20:1 from_host.mid
1108 $ aplaymidi -p 24:1 to_gadget.mid
1110 The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1111 translated from/to UMP packets on the gadget. It's bound to only
1114 The current operation mode can be observed in ALSA control element
1115 "Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example::
1117 $ amixer -c1 contents
1118 numid=1,iface=RAWMIDI,name='Operation Mode'
1119 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
1122 where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1123 The example above shows it's running in 2, i.e. MIDI 2.0.