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 max_segment_size Segment size required for P2P connections. This
460 will set MTU to 14 bytes
461 ======================= ==================================================
463 and after creating the functions/ncm.<instance name> they contain default
464 values: qmult is 5, dev_addr and host_addr are randomly selected.
465 The ifname can be written to if the function is not bound. A write must be an
466 interface pattern such as "usb%d", which will cause the net core to choose the
467 next free usbX interface. By default, it is set to "usb%d".
469 Testing the NCM function
470 ------------------------
472 Configure IP addresses of the device and the host. Then:
485 The function is provided by usb_f_obex.ko module.
487 Function-specific configfs interface
488 ------------------------------------
490 The function name to use when creating the function directory is "obex".
491 The OBEX function provides just one attribute in its function directory:
495 The attribute is read-only.
497 There can be at most 4 ACM/generic serial/OBEX ports in the system.
499 Testing the OBEX function
500 -------------------------
504 seriald -f /dev/ttyGS<Y> -s 1024
508 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
509 -t<out endpoint addr> -r<in endpoint addr>
511 where seriald and serialc are Felipe's utilities found here:
513 https://github.com/felipebalbi/usb-tools.git master
518 The function is provided by usb_f_phonet.ko module.
520 Function-specific configfs interface
521 ------------------------------------
523 The function name to use when creating the function directory is "phonet".
524 The PHONET function provides just one attribute in its function directory:
526 =============== ==================================================
527 ifname network device interface name associated with this
529 =============== ==================================================
531 Testing the PHONET function
532 ---------------------------
534 It is not possible to test the SOCK_STREAM protocol without a specific piece
535 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
536 in the past I had to apply the patch mentioned here:
538 http://www.spinics.net/lists/linux-usb/msg85689.html
540 These tools are required:
542 git://git.gitorious.org/meego-cellular/phonet-utils.git
546 $ ./phonet -a 0x10 -i usbpn0
547 $ ./pnroute add 0x6c usbpn0
548 $./pnroute add 0x10 usbpn0
553 $ ./phonet -a 0x6c -i upnlink0
554 $ ./pnroute add 0x10 upnlink0
555 $ ifconfig upnlink0 up
557 Then a test program can be used::
559 http://www.spinics.net/lists/linux-usb/msg85690.html
563 $ ./pnxmit -a 0x6c -r
567 $ ./pnxmit -a 0x10 -s 0x6c
569 As a result some data should be sent from host to device.
570 Then the other way round:
574 $ ./pnxmit -a 0x10 -r
578 $ ./pnxmit -a 0x6c -s 0x10
583 The function is provided by usb_f_rndis.ko module.
585 Function-specific configfs interface
586 ------------------------------------
588 The function name to use when creating the function directory is "rndis".
589 The RNDIS function provides these attributes in its function directory:
591 =============== ==================================================
592 ifname network device interface name associated with this
594 qmult queue length multiplier for high and super speed
595 host_addr MAC address of host's end of this
596 Ethernet over USB link
597 dev_addr MAC address of device's end of this
598 Ethernet over USB link
599 =============== ==================================================
601 and after creating the functions/rndis.<instance name> they contain default
602 values: qmult is 5, dev_addr and host_addr are randomly selected.
603 The ifname can be written to if the function is not bound. A write must be an
604 interface pattern such as "usb%d", which will cause the net core to choose the
605 next free usbX interface. By default, it is set to "usb%d".
607 Testing the RNDIS function
608 --------------------------
610 Configure IP addresses of the device and the host. Then:
623 The function is provided by usb_f_gser.ko module.
625 Function-specific configfs interface
626 ------------------------------------
628 The function name to use when creating the function directory is "gser".
629 The SERIAL function provides just one attribute in its function directory:
633 The attribute is read-only.
635 There can be at most 4 ACM/generic serial/OBEX ports in the system.
637 Testing the SERIAL function
638 ---------------------------
643 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
653 then the other way round
663 15. SOURCESINK function
664 =======================
666 The function is provided by usb_f_ss_lb.ko module.
668 Function-specific configfs interface
669 ------------------------------------
671 The function name to use when creating the function directory is "SourceSink".
672 The SOURCESINK function provides these attributes in its function directory:
674 =============== ==================================
675 pattern 0 (all zeros), 1 (mod63), 2 (none)
677 isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss)
678 isoc_mult 0..2 (hs/ss only)
679 isoc_maxburst 0..15 (ss only)
680 bulk_buflen buffer length
681 bulk_qlen depth of queue for bulk
682 iso_qlen depth of queue for iso
683 =============== ==================================
685 Testing the SOURCESINK function
686 -------------------------------
688 device: run the gadget
690 host: test-usb (tools/usb/testusb.c)
693 16. UAC1 function (legacy implementation)
694 =========================================
696 The function is provided by usb_f_uac1_legacy.ko module.
698 Function-specific configfs interface
699 ------------------------------------
701 The function name to use when creating the function directory
703 The uac1 function provides these attributes in its function directory:
705 =============== ====================================
706 audio_buf_size audio buffer size
707 fn_cap capture pcm device file name
708 fn_cntl control device file name
709 fn_play playback pcm device file name
710 req_buf_size ISO OUT endpoint request buffer size
711 req_count ISO OUT endpoint request count
712 =============== ====================================
714 The attributes have sane default values.
716 Testing the UAC1 function
717 -------------------------
719 device: run the gadget
723 aplay -l # should list our USB Audio Gadget
728 The function is provided by usb_f_uac2.ko module.
730 Function-specific configfs interface
731 ------------------------------------
733 The function name to use when creating the function directory is "uac2".
734 The uac2 function provides these attributes in its function directory:
736 ================ ====================================================
737 c_chmask capture channel mask
738 c_srate list of capture sampling rates (comma-separated)
739 c_ssize capture sample size (bytes)
740 c_sync capture synchronization type (async/adaptive)
741 c_mute_present capture mute control enable
742 c_volume_present capture volume control enable
743 c_volume_min capture volume control min value (in 1/256 dB)
744 c_volume_max capture volume control max value (in 1/256 dB)
745 c_volume_res capture volume control resolution (in 1/256 dB)
746 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto)
747 fb_max maximum extra bandwidth in async mode
748 p_chmask playback channel mask
749 p_srate list of playback sampling rates (comma-separated)
750 p_ssize playback sample size (bytes)
751 p_mute_present playback mute control enable
752 p_volume_present playback volume control enable
753 p_volume_min playback volume control min value (in 1/256 dB)
754 p_volume_max playback volume control max value (in 1/256 dB)
755 p_volume_res playback volume control resolution (in 1/256 dB)
756 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto)
757 req_number the number of pre-allocated request for both capture
759 function_name name of the interface
760 c_terminal_type code of the capture terminal type
761 p_terminal_type code of the playback terminal type
762 ================ ====================================================
764 The attributes have sane default values.
766 Testing the UAC2 function
767 -------------------------
769 device: run the gadget
770 host: aplay -l # should list our USB Audio Gadget
772 This function does not require real hardware support, it just
773 sends a stream of audio data to/from the host. In order to
774 actually hear something at the device side, a command similar
775 to this must be used at the device side::
777 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
781 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
782 aplay -D default:CARD=OdroidU3
787 The function is provided by usb_f_uvc.ko module.
789 Function-specific configfs interface
790 ------------------------------------
792 The function name to use when creating the function directory is "uvc".
793 The uvc function provides these attributes in its function directory:
795 =================== ================================================
796 streaming_interval interval for polling endpoint for data transfers
797 streaming_maxburst bMaxBurst for super speed companion descriptor
798 streaming_maxpacket maximum packet size this endpoint is capable of
799 sending or receiving when this configuration is
801 function_name name of the interface
802 =================== ================================================
804 There are also "control" and "streaming" subdirectories, each of which contain
805 a number of their subdirectories. There are some sane defaults provided, but
806 the user must provide the following:
808 ================== ====================================================
809 control header create in control/header, link from control/class/fs
810 and/or control/class/ss
811 streaming header create in streaming/header, link from
812 streaming/class/fs and/or streaming/class/hs and/or
814 format description create in streaming/mjpeg and/or
815 streaming/uncompressed
816 frame description create in streaming/mjpeg/<format> and/or in
817 streaming/uncompressed/<format>
818 ================== ====================================================
820 Each frame description contains frame interval specification, and each
821 such specification consists of a number of lines with an interval value
822 in each line. The rules stated above are best illustrated with an example::
824 # mkdir functions/uvc.usb0/control/header/h
825 # cd functions/uvc.usb0/control/
826 # ln -s header/h class/fs
827 # ln -s header/h class/ss
828 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
829 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
834 # cd $GADGET_CONFIGFS_ROOT
835 # mkdir functions/uvc.usb0/streaming/header/h
836 # cd functions/uvc.usb0/streaming/header/h
837 # ln -s ../../uncompressed/u
839 # ln -s ../../header/h
841 # ln -s ../../header/h
843 # ln -s ../../header/h
846 Testing the UVC function
847 ------------------------
849 device: run the gadget, modprobe vivid::
851 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
853 where uvc-gadget is this program:
854 http://git.ideasonboard.org/uvc-gadget.git
858 http://www.spinics.net/lists/linux-usb/msg99220.html
867 The function is provided by usb_f_printer.ko module.
869 Function-specific configfs interface
870 ------------------------------------
872 The function name to use when creating the function directory is "printer".
873 The printer function provides these attributes in its function directory:
875 ========== ===========================================
876 pnp_string Data to be passed to the host in pnp string
877 q_len Number of requests per endpoint
878 ========== ===========================================
880 Testing the PRINTER function
881 ----------------------------
883 The most basic testing:
885 device: run the gadget::
887 # ls -l /devices/virtual/usb_printer_gadget/
889 should show g_printer<number>.
891 If udev is active, then /dev/g_printer<number> should appear automatically.
895 If udev is active, then e.g. /dev/usb/lp0 should appear.
897 host->device transmission:
901 # cat /dev/g_printer<number>
907 device->host transmission::
909 # cat > /dev/g_printer<number>
915 More advanced testing can be done with the prn_example
916 described in Documentation/usb/gadget_printer.rst.
919 20. UAC1 function (virtual ALSA card, using u_audio API)
920 ========================================================
922 The function is provided by usb_f_uac1.ko module.
923 It will create a virtual ALSA card and the audio streams are simply
924 sinked to and sourced from it.
926 Function-specific configfs interface
927 ------------------------------------
929 The function name to use when creating the function directory is "uac1".
930 The uac1 function provides these attributes in its function directory:
932 ================ ====================================================
933 c_chmask capture channel mask
934 c_srate list of capture sampling rates (comma-separated)
935 c_ssize capture sample size (bytes)
936 c_mute_present capture mute control enable
937 c_volume_present capture volume control enable
938 c_volume_min capture volume control min value (in 1/256 dB)
939 c_volume_max capture volume control max value (in 1/256 dB)
940 c_volume_res capture volume control resolution (in 1/256 dB)
941 p_chmask playback channel mask
942 p_srate list of playback sampling rates (comma-separated)
943 p_ssize playback sample size (bytes)
944 p_mute_present playback mute control enable
945 p_volume_present playback volume control enable
946 p_volume_min playback volume control min value (in 1/256 dB)
947 p_volume_max playback volume control max value (in 1/256 dB)
948 p_volume_res playback volume control resolution (in 1/256 dB)
949 req_number the number of pre-allocated requests for both capture
951 function_name name of the interface
952 ================ ====================================================
954 The attributes have sane default values.
956 Testing the UAC1 function
957 -------------------------
959 device: run the gadget
960 host: aplay -l # should list our USB Audio Gadget
962 This function does not require real hardware support, it just
963 sends a stream of audio data to/from the host. In order to
964 actually hear something at the device side, a command similar
965 to this must be used at the device side::
967 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
971 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
972 aplay -D default:CARD=OdroidU3
978 The function is provided by usb_f_midi2.ko module.
979 It will create a virtual ALSA card containing a UMP rawmidi device
980 where the UMP packet is looped back. In addition, a legacy rawmidi
981 device is created. The UMP rawmidi is bound with ALSA sequencer
984 Function-specific configfs interface
985 ------------------------------------
987 The function name to use when creating the function directory is "midi2".
988 The midi2 function provides these attributes in its function directory
989 as the card top-level information:
991 ============= =================================================
992 process_ump Bool flag to process UMP Stream messages (0 or 1)
993 static_block Bool flag for static blocks (0 or 1)
994 iface_name Optional interface name string
995 ============= =================================================
997 The directory contains a subdirectory "ep.0", and this provides the
998 attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):
1000 ============= =================================================
1001 protocol_caps MIDI protocol capabilities;
1002 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols
1003 protocol Default MIDI protocol (either 1 or 2)
1004 ep_name UMP Endpoint name string
1005 product_id Product ID string
1006 manufacturer Manufacture ID number (24 bit)
1007 family Device family ID number (16 bit)
1008 model Device model ID number (16 bit)
1009 sw_revision Software revision (32 bit)
1010 ============= =================================================
1012 Each Endpoint subdirectory contains a subdirectory "block.0", which
1013 represents the Function Block for Block 0 information.
1016 ================= ===============================================
1017 name Function Block name string
1018 direction Direction of this FB
1019 1: input, 2: output, or 3: bidirectional
1020 first_group The first UMP Group number (0-15)
1021 num_groups The number of groups in this FB (1-16)
1022 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15)
1023 midi1_num_groups The number of groups for MIDI 1.0 (0-16)
1024 ui_hint UI-hint of this FB
1025 0: unknown, 1: receiver, 2: sender, 3: both
1026 midi_ci_verison Supported MIDI-CI version number (8 bit)
1027 is_midi1 Legacy MIDI 1.0 device (0-2)
1029 1: MIDI 1.0 without restriction, or
1030 2: MIDI 1.0 with low speed
1031 sysex8_streams Max number of SysEx8 streams (8 bit)
1032 active Bool flag for FB activity (0 or 1)
1033 ================= ===============================================
1035 If multiple Function Blocks are required, you can add more Function
1036 Blocks by creating subdirectories "block.<num>" with the corresponding
1037 Function Block number (1, 2, ....). The FB subdirectories can be
1038 dynamically removed, too. Note that the Function Block numbers must be
1041 Similarly, if you multiple UMP Endpoints are required, you can add
1042 more Endpoints by creating subdirectories "ep.<num>". The number must
1045 For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0
1046 to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.
1048 Testing the MIDI2 function
1049 --------------------------
1051 On the device: run the gadget, and running::
1053 $ cat /proc/asound/cards
1055 will show a new sound card containing a MIDI2 device.
1059 $ cat /proc/asound/cards
1061 will show a new sound card containing either MIDI1 or MIDI2 device,
1062 depending on the USB audio driver configuration.
1064 On both, when ALSA sequencer is enabled on the host, you can find the
1065 UMP MIDI client such as "MIDI 2.0 Gadget".
1067 As the driver simply loops back the data, there is no need for a real
1068 device just for testing.
1070 For testing a MIDI input from the gadget to the host (e.g. emulating a
1071 MIDI keyboard), you can send a MIDI stream like the following.
1077 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]
1079 1 'Group 1 (MIDI 2.0 Gadget I/O)'
1080 $ aplaymidi -p 20:1 to_host.mid
1086 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]
1088 1 'Group 1 (MIDI 2.0 Gadget I/O)'
1089 $ arecordmidi -p 24:1 from_gadget.mid
1091 If you have a UMP-capable application, you can use the UMP port to
1092 send/receive the raw UMP packets, too. For example, aseqdump program
1093 with UMP support can receive from UMP port. On the host::
1095 $ aseqdump -u 2 -p 24:1
1096 Waiting for data. Press Ctrl+C to end.
1097 Source Group Event Ch Data
1098 24:1 Group 0, Program change 0, program 0, Bank select 0:0
1099 24:1 Group 0, Channel pressure 0, value 0x80000000
1101 For testing a MIDI output to the gadget to the host (e.g. emulating a
1102 MIDI synth), it'll be just other way round.
1106 $ arecordmidi -p 20:1 from_host.mid
1110 $ aplaymidi -p 24:1 to_gadget.mid
1112 The access to MIDI 1.0 on altset 0 on the host is supported, and it's
1113 translated from/to UMP packets on the gadget. It's bound to only
1116 The current operation mode can be observed in ALSA control element
1117 "Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example::
1119 $ amixer -c1 contents
1120 numid=1,iface=RAWMIDI,name='Operation Mode'
1121 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0
1124 where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).
1125 The example above shows it's running in 2, i.e. MIDI 2.0.