1153 lines · plain
1==============2Gadget Testing3==============4 5This file summarizes information on basic testing of USB functions6provided by gadgets.7 8.. contents9 10 1. ACM function11 2. ECM function12 3. ECM subset function13 4. EEM function14 5. FFS function15 6. HID function16 7. LOOPBACK function17 8. MASS STORAGE function18 9. MIDI function19 10. NCM function20 11. OBEX function21 12. PHONET function22 13. RNDIS function23 14. SERIAL function24 15. SOURCESINK function25 16. UAC1 function (legacy implementation)26 17. UAC2 function27 18. UVC function28 19. PRINTER function29 20. UAC1 function (new API)30 21. MIDI2 function31 32 331. ACM function34===============35 36The function is provided by usb_f_acm.ko module.37 38Function-specific configfs interface39------------------------------------40 41The function name to use when creating the function directory is "acm".42The ACM function provides just one attribute in its function directory:43 44 port_num45 46The attribute is read-only.47 48There can be at most 4 ACM/generic serial/OBEX ports in the system.49 50 51Testing the ACM function52------------------------53 54On the host::55 56 cat > /dev/ttyACM<X>57 58On the device::59 60 cat /dev/ttyGS<Y>61 62then the other way round63 64On the device::65 66 cat > /dev/ttyGS<Y>67 68On the host::69 70 cat /dev/ttyACM<X>71 722. ECM function73===============74 75The function is provided by usb_f_ecm.ko module.76 77Function-specific configfs interface78------------------------------------79 80The function name to use when creating the function directory is "ecm".81The ECM function provides these attributes in its function directory:82 83 =============== ==================================================84 ifname network device interface name associated with this85 function instance86 qmult queue length multiplier for high and super speed87 host_addr MAC address of host's end of this88 Ethernet over USB link89 dev_addr MAC address of device's end of this90 Ethernet over USB link91 =============== ==================================================92 93and after creating the functions/ecm.<instance name> they contain default94values: qmult is 5, dev_addr and host_addr are randomly selected.95The ifname can be written to if the function is not bound. A write must be an96interface pattern such as "usb%d", which will cause the net core to choose the97next free usbX interface. By default, it is set to "usb%d".98 99Testing the ECM function100------------------------101 102Configure IP addresses of the device and the host. Then:103 104On the device::105 106 ping <host's IP>107 108On the host::109 110 ping <device's IP>111 1123. ECM subset function113======================114 115The function is provided by usb_f_ecm_subset.ko module.116 117Function-specific configfs interface118------------------------------------119 120The function name to use when creating the function directory is "geth".121The ECM subset function provides these attributes in its function directory:122 123 =============== ==================================================124 ifname network device interface name associated with this125 function instance126 qmult queue length multiplier for high and super speed127 host_addr MAC address of host's end of this128 Ethernet over USB link129 dev_addr MAC address of device's end of this130 Ethernet over USB link131 =============== ==================================================132 133and after creating the functions/ecm.<instance name> they contain default134values: qmult is 5, dev_addr and host_addr are randomly selected.135The ifname can be written to if the function is not bound. A write must be an136interface pattern such as "usb%d", which will cause the net core to choose the137next free usbX interface. By default, it is set to "usb%d".138 139Testing the ECM subset function140-------------------------------141 142Configure IP addresses of the device and the host. Then:143 144On the device::145 146 ping <host's IP>147 148On the host::149 150 ping <device's IP>151 1524. EEM function153===============154 155The function is provided by usb_f_eem.ko module.156 157Function-specific configfs interface158------------------------------------159 160The function name to use when creating the function directory is "eem".161The EEM function provides these attributes in its function directory:162 163 =============== ==================================================164 ifname network device interface name associated with this165 function instance166 qmult queue length multiplier for high and super speed167 host_addr MAC address of host's end of this168 Ethernet over USB link169 dev_addr MAC address of device's end of this170 Ethernet over USB link171 =============== ==================================================172 173and after creating the functions/eem.<instance name> they contain default174values: qmult is 5, dev_addr and host_addr are randomly selected.175The ifname can be written to if the function is not bound. A write must be an176interface pattern such as "usb%d", which will cause the net core to choose the177next free usbX interface. By default, it is set to "usb%d".178 179Testing the EEM function180------------------------181 182Configure IP addresses of the device and the host. Then:183 184On the device::185 186 ping <host's IP>187 188On the host::189 190 ping <device's IP>191 1925. FFS function193===============194 195The function is provided by usb_f_fs.ko module.196 197Function-specific configfs interface198------------------------------------199 200The function name to use when creating the function directory is "ffs".201The function directory is intentionally empty and not modifiable.202 203After creating the directory there is a new instance (a "device") of FunctionFS204available in the system. Once a "device" is available, the user should follow205the standard procedure for using FunctionFS (mount it, run the userspace206process which implements the function proper). The gadget should be enabled207by writing a suitable string to usb_gadget/<gadget>/UDC.208 209The FFS function provides just one attribute in its function directory:210 211 ready212 213The attribute is read-only and signals if the function is ready (1) to be214used, E.G. if userspace has written descriptors and strings to ep0, so215the gadget can be enabled.216 217Testing the FFS function218------------------------219 220On the device: start the function's userspace daemon, enable the gadget221 222On the host: use the USB function provided by the device223 2246. HID function225===============226 227The function is provided by usb_f_hid.ko module.228 229Function-specific configfs interface230------------------------------------231 232The function name to use when creating the function directory is "hid".233The HID function provides these attributes in its function directory:234 235 =============== ===========================================236 protocol HID protocol to use237 report_desc data to be used in HID reports, except data238 passed with /dev/hidg<X>239 report_length HID report length240 subclass HID subclass to use241 =============== ===========================================242 243For a keyboard the protocol and the subclass are 1, the report_length is 8,244while the report_desc is::245 246 $ hd my_report_desc247 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...|251 0000003f252 253Such a sequence of bytes can be stored to the attribute with echo::254 255 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....256 257Testing the HID function258------------------------259 260Device:261 262- create the gadget263- connect the gadget to a host, preferably not the one used264 to control the gadget265- run a program which writes to /dev/hidg<N>, e.g.266 a userspace program found in Documentation/usb/gadget_hid.rst::267 268 $ ./hid_gadget_test /dev/hidg0 keyboard269 270Host:271 272- observe the keystrokes from the gadget273 2747. LOOPBACK function275====================276 277The function is provided by usb_f_ss_lb.ko module.278 279Function-specific configfs interface280------------------------------------281 282The function name to use when creating the function directory is "Loopback".283The LOOPBACK function provides these attributes in its function directory:284 285 =============== =======================286 qlen depth of loopback queue287 bulk_buflen buffer length288 =============== =======================289 290Testing the LOOPBACK function291-----------------------------292 293device: run the gadget294 295host: test-usb (tools/usb/testusb.c)296 2978. MASS STORAGE function298========================299 300The function is provided by usb_f_mass_storage.ko module.301 302Function-specific configfs interface303------------------------------------304 305The function name to use when creating the function directory is "mass_storage".306The MASS STORAGE function provides these attributes in its directory:307files:308 309 =============== ==============================================310 stall Set to permit function to halt bulk endpoints.311 Disabled on some USB devices known not to work312 correctly. You should set it to true.313 num_buffers Number of pipeline buffers. Valid numbers314 are 2..4. Available only if315 CONFIG_USB_GADGET_DEBUG_FILES is set.316 =============== ==============================================317 318and a default lun.0 directory corresponding to SCSI LUN #0.319 320A new lun can be added with mkdir::321 322 $ mkdir functions/mass_storage.0/partition.5323 324Lun numbering does not have to be continuous, except for lun #0 which is325created by default. A maximum of 8 luns can be specified and they all must be326named following the <name>.<number> scheme. The numbers can be 0..8.327Probably a good convention is to name the luns "lun.<number>",328although it is not mandatory.329 330In each lun directory there are the following attribute files:331 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 be336 read-only. This is implied if CD-ROM emulation337 is enabled as well as when it was impossible338 to open "filename" in R/W mode.339 removable Flag specifying that LUN shall be indicated as340 being removable.341 cdrom Flag specifying that LUN shall be reported as342 being a CD-ROM.343 nofua Flag specifying that FUA flag344 in SCSI WRITE(10,12)345 forced_eject This write-only file is useful only when346 the function is active. It causes the backing347 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 will350 result in ejection.351 =============== ==============================================352 353Testing the MASS STORAGE function354---------------------------------355 356device: connect the gadget, enable it357host: dmesg, see the USB drives appear (if system configured to automatically358mount)359 3609. MIDI function361================362 363The function is provided by usb_f_midi.ko module.364 365Function-specific configfs interface366------------------------------------367 368The function name to use when creating the function directory is "midi".369The MIDI function provides these attributes in its function directory:370 371 =============== ====================================372 buflen MIDI buffer length373 id ID string for the USB MIDI adapter374 in_ports number of MIDI input ports375 index index value for the USB MIDI adapter376 out_ports number of MIDI output ports377 qlen USB read request queue length378 =============== ====================================379 380Testing the MIDI function381-------------------------382 383There are two cases: playing a mid from the gadget to384the host and playing a mid from the host to the gadget.385 3861) Playing a mid from the gadget to the host:387 388host::389 390 $ arecordmidi -l391 Port Client name Port name392 14:0 Midi Through Midi Through Port-0393 24:0 MIDI Gadget MIDI Gadget MIDI 1394 $ arecordmidi -p 24:0 from_gadget.mid395 396gadget::397 398 $ aplaymidi -l399 Port Client name Port name400 20:0 f_midi f_midi401 402 $ aplaymidi -p 20:0 to_host.mid403 4042) Playing a mid from the host to the gadget405 406gadget::407 408 $ arecordmidi -l409 Port Client name Port name410 20:0 f_midi f_midi411 412 $ arecordmidi -p 20:0 from_host.mid413 414host::415 416 $ aplaymidi -l417 Port Client name Port name418 14:0 Midi Through Midi Through Port-0419 24:0 MIDI Gadget MIDI Gadget MIDI 1420 421 $ aplaymidi -p24:0 to_gadget.mid422 423The from_gadget.mid should sound identical to the to_host.mid.424 425The from_host.id should sound identical to the to_gadget.mid.426 427MIDI files can be played to speakers/headphones with e.g. timidity installed::428 429 $ aplaymidi -l430 Port Client name Port name431 14:0 Midi Through Midi Through Port-0432 24:0 MIDI Gadget MIDI Gadget MIDI 1433 128:0 TiMidity TiMidity port 0434 128:1 TiMidity TiMidity port 1435 128:2 TiMidity TiMidity port 2436 128:3 TiMidity TiMidity port 3437 438 $ aplaymidi -p 128:0 file.mid439 440MIDI ports can be logically connected using the aconnect utility, e.g.::441 442 $ aconnect 24:0 128:0 # try it on the host443 444After the gadget's MIDI port is connected to timidity's MIDI port,445whatever is played at the gadget side with aplaymidi -l is audible446in host's speakers/headphones.447 44810. NCM function449================450 451The function is provided by usb_f_ncm.ko module.452 453Function-specific configfs interface454------------------------------------455 456The function name to use when creating the function directory is "ncm".457The NCM function provides these attributes in its function directory:458 459 ======================= ==================================================460 ifname network device interface name associated with this461 function instance462 qmult queue length multiplier for high and super speed463 host_addr MAC address of host's end of this464 Ethernet over USB link465 dev_addr MAC address of device's end of this466 Ethernet over USB link467 max_segment_size Segment size required for P2P connections. This468 will set MTU to 14 bytes469 ======================= ==================================================470 471and after creating the functions/ncm.<instance name> they contain default472values: qmult is 5, dev_addr and host_addr are randomly selected.473The ifname can be written to if the function is not bound. A write must be an474interface pattern such as "usb%d", which will cause the net core to choose the475next free usbX interface. By default, it is set to "usb%d".476 477Testing the NCM function478------------------------479 480Configure IP addresses of the device and the host. Then:481 482On the device::483 484 ping <host's IP>485 486On the host::487 488 ping <device's IP>489 49011. OBEX function491=================492 493The function is provided by usb_f_obex.ko module.494 495Function-specific configfs interface496------------------------------------497 498The function name to use when creating the function directory is "obex".499The OBEX function provides just one attribute in its function directory:500 501 port_num502 503The attribute is read-only.504 505There can be at most 4 ACM/generic serial/OBEX ports in the system.506 507Testing the OBEX function508-------------------------509 510On device::511 512 seriald -f /dev/ttyGS<Y> -s 1024513 514On host::515 516 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \517 -t<out endpoint addr> -r<in endpoint addr>518 519where seriald and serialc are Felipe's utilities found here:520 521 https://github.com/felipebalbi/usb-tools.git master522 52312. PHONET function524===================525 526The function is provided by usb_f_phonet.ko module.527 528Function-specific configfs interface529------------------------------------530 531The function name to use when creating the function directory is "phonet".532The PHONET function provides just one attribute in its function directory:533 534 =============== ==================================================535 ifname network device interface name associated with this536 function instance537 =============== ==================================================538 539Testing the PHONET function540---------------------------541 542It is not possible to test the SOCK_STREAM protocol without a specific piece543of hardware, so only SOCK_DGRAM has been tested. For the latter to work,544in the past I had to apply the patch mentioned here:545 546http://www.spinics.net/lists/linux-usb/msg85689.html547 548These tools are required:549 550git://git.gitorious.org/meego-cellular/phonet-utils.git551 552On the host::553 554 $ ./phonet -a 0x10 -i usbpn0555 $ ./pnroute add 0x6c usbpn0556 $./pnroute add 0x10 usbpn0557 $ ifconfig usbpn0 up558 559On the device::560 561 $ ./phonet -a 0x6c -i upnlink0562 $ ./pnroute add 0x10 upnlink0563 $ ifconfig upnlink0 up564 565Then a test program can be used::566 567 http://www.spinics.net/lists/linux-usb/msg85690.html568 569On the device::570 571 $ ./pnxmit -a 0x6c -r572 573On the host::574 575 $ ./pnxmit -a 0x10 -s 0x6c576 577As a result some data should be sent from host to device.578Then the other way round:579 580On the host::581 582 $ ./pnxmit -a 0x10 -r583 584On the device::585 586 $ ./pnxmit -a 0x6c -s 0x10587 58813. RNDIS function589==================590 591The function is provided by usb_f_rndis.ko module.592 593Function-specific configfs interface594------------------------------------595 596The function name to use when creating the function directory is "rndis".597The RNDIS function provides these attributes in its function directory:598 599 =============== ==================================================600 ifname network device interface name associated with this601 function instance602 qmult queue length multiplier for high and super speed603 host_addr MAC address of host's end of this604 Ethernet over USB link605 dev_addr MAC address of device's end of this606 Ethernet over USB link607 =============== ==================================================608 609and after creating the functions/rndis.<instance name> they contain default610values: qmult is 5, dev_addr and host_addr are randomly selected.611The ifname can be written to if the function is not bound. A write must be an612interface pattern such as "usb%d", which will cause the net core to choose the613next free usbX interface. By default, it is set to "usb%d".614 615Testing the RNDIS function616--------------------------617 618Configure IP addresses of the device and the host. Then:619 620On the device::621 622 ping <host's IP>623 624On the host::625 626 ping <device's IP>627 62814. SERIAL function629===================630 631The function is provided by usb_f_gser.ko module.632 633Function-specific configfs interface634------------------------------------635 636The function name to use when creating the function directory is "gser".637The SERIAL function provides just one attribute in its function directory:638 639 port_num640 641The attribute is read-only.642 643There can be at most 4 ACM/generic serial/OBEX ports in the system.644 645Testing the SERIAL function646---------------------------647 648On host::649 650 insmod usbserial651 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id652 653On host::654 655 cat > /dev/ttyUSB<X>656 657On target::658 659 cat /dev/ttyGS<Y>660 661then the other way round662 663On target::664 665 cat > /dev/ttyGS<Y>666 667On host::668 669 cat /dev/ttyUSB<X>670 67115. SOURCESINK function672=======================673 674The function is provided by usb_f_ss_lb.ko module.675 676Function-specific configfs interface677------------------------------------678 679The function name to use when creating the function directory is "SourceSink".680The SOURCESINK function provides these attributes in its function directory:681 682 =============== ==================================683 pattern 0 (all zeros), 1 (mod63), 2 (none)684 isoc_interval 1..16685 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 length689 bulk_qlen depth of queue for bulk690 iso_qlen depth of queue for iso691 =============== ==================================692 693Testing the SOURCESINK function694-------------------------------695 696device: run the gadget697 698host: test-usb (tools/usb/testusb.c)699 700 70116. UAC1 function (legacy implementation)702=========================================703 704The function is provided by usb_f_uac1_legacy.ko module.705 706Function-specific configfs interface707------------------------------------708 709The function name to use when creating the function directory710is "uac1_legacy".711The uac1 function provides these attributes in its function directory:712 713 =============== ====================================714 audio_buf_size audio buffer size715 fn_cap capture pcm device file name716 fn_cntl control device file name717 fn_play playback pcm device file name718 req_buf_size ISO OUT endpoint request buffer size719 req_count ISO OUT endpoint request count720 =============== ====================================721 722The attributes have sane default values.723 724Testing the UAC1 function725-------------------------726 727device: run the gadget728 729host::730 731 aplay -l # should list our USB Audio Gadget732 73317. UAC2 function734=================735 736The function is provided by usb_f_uac2.ko module.737 738Function-specific configfs interface739------------------------------------740 741The function name to use when creating the function directory is "uac2".742The uac2 function provides these attributes in its function directory:743 744 ================ ====================================================745 c_chmask capture channel mask746 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 enable750 c_volume_present capture volume control enable751 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 mode756 p_chmask playback channel mask757 p_srate list of playback sampling rates (comma-separated)758 p_ssize playback sample size (bytes)759 p_mute_present playback mute control enable760 p_volume_present playback volume control enable761 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 capture766 and playback767 function_name name of the interface768 if_ctrl_name topology control name769 clksrc_in_name input clock name770 clksrc_out_name output clock name771 p_it_name playback input terminal name772 p_it_ch_name playback input first channel name773 p_ot_name playback output terminal name774 p_fu_vol_name playback function unit name775 c_it_name capture input terminal name776 c_it_ch_name capture input first channel name777 c_ot_name capture output terminal name778 c_fu_vol_name capture functional unit name779 c_terminal_type code of the capture terminal type780 p_terminal_type code of the playback terminal type781 ================ ====================================================782 783The attributes have sane default values.784 785Testing the UAC2 function786-------------------------787 788device: run the gadget789host: aplay -l # should list our USB Audio Gadget790 791This function does not require real hardware support, it just792sends a stream of audio data to/from the host. In order to793actually hear something at the device side, a command similar794to this must be used at the device side::795 796 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &797 798e.g.::799 800 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \801 aplay -D default:CARD=OdroidU3802 80318. UVC function804================805 806The function is provided by usb_f_uvc.ko module.807 808Function-specific configfs interface809------------------------------------810 811The function name to use when creating the function directory is "uvc".812The uvc function provides these attributes in its function directory:813 814 =================== ================================================815 streaming_interval interval for polling endpoint for data transfers816 streaming_maxburst bMaxBurst for super speed companion descriptor817 streaming_maxpacket maximum packet size this endpoint is capable of818 sending or receiving when this configuration is819 selected820 function_name name of the interface821 =================== ================================================822 823There are also "control" and "streaming" subdirectories, each of which contain824a number of their subdirectories. There are some sane defaults provided, but825the user must provide the following:826 827 ================== ====================================================828 control header create in control/header, link from control/class/fs829 and/or control/class/ss830 streaming header create in streaming/header, link from831 streaming/class/fs and/or streaming/class/hs and/or832 streaming/class/ss833 format description create in streaming/mjpeg and/or834 streaming/uncompressed835 frame description create in streaming/mjpeg/<format> and/or in836 streaming/uncompressed/<format>837 ================== ====================================================838 839Each frame description contains frame interval specification, and each840such specification consists of a number of lines with an interval value841in each line. The rules stated above are best illustrated with an example::842 843 # mkdir functions/uvc.usb0/control/header/h844 # cd functions/uvc.usb0/control/845 # ln -s header/h class/fs846 # ln -s header/h class/ss847 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p848 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval849 666666850 1000000851 5000000852 EOF853 # cd $GADGET_CONFIGFS_ROOT854 # mkdir functions/uvc.usb0/streaming/header/h855 # cd functions/uvc.usb0/streaming/header/h856 # ln -s ../../uncompressed/u857 # cd ../../class/fs858 # ln -s ../../header/h859 # cd ../../class/hs860 # ln -s ../../header/h861 # cd ../../class/ss862 # ln -s ../../header/h863 864 865Testing the UVC function866------------------------867 868device: run the gadget, modprobe vivid::869 870 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>871 872where uvc-gadget is this program:873 http://git.ideasonboard.org/uvc-gadget.git874 875with these patches:876 877 http://www.spinics.net/lists/linux-usb/msg99220.html878 879host::880 881 luvcview -f yuv882 88319. PRINTER function884====================885 886The function is provided by usb_f_printer.ko module.887 888Function-specific configfs interface889------------------------------------890 891The function name to use when creating the function directory is "printer".892The printer function provides these attributes in its function directory:893 894 ========== ===========================================895 pnp_string Data to be passed to the host in pnp string896 q_len Number of requests per endpoint897 ========== ===========================================898 899Testing the PRINTER function900----------------------------901 902The most basic testing:903 904device: run the gadget::905 906 # ls -l /devices/virtual/usb_printer_gadget/907 908should show g_printer<number>.909 910If udev is active, then /dev/g_printer<number> should appear automatically.911 912host:913 914If udev is active, then e.g. /dev/usb/lp0 should appear.915 916host->device transmission:917 918device::919 920 # cat /dev/g_printer<number>921 922host::923 924 # cat > /dev/usb/lp0925 926device->host transmission::927 928 # cat > /dev/g_printer<number>929 930host::931 932 # cat /dev/usb/lp0933 934More advanced testing can be done with the prn_example935described in Documentation/usb/gadget_printer.rst.936 937 93820. UAC1 function (virtual ALSA card, using u_audio API)939========================================================940 941The function is provided by usb_f_uac1.ko module.942It will create a virtual ALSA card and the audio streams are simply943sinked to and sourced from it.944 945Function-specific configfs interface946------------------------------------947 948The function name to use when creating the function directory is "uac1".949The uac1 function provides these attributes in its function directory:950 951 ================ ====================================================952 c_chmask capture channel mask953 c_srate list of capture sampling rates (comma-separated)954 c_ssize capture sample size (bytes)955 c_mute_present capture mute control enable956 c_volume_present capture volume control enable957 c_volume_min capture volume control min value (in 1/256 dB)958 c_volume_max capture volume control max value (in 1/256 dB)959 c_volume_res capture volume control resolution (in 1/256 dB)960 p_chmask playback channel mask961 p_srate list of playback sampling rates (comma-separated)962 p_ssize playback sample size (bytes)963 p_mute_present playback mute control enable964 p_volume_present playback volume control enable965 p_volume_min playback volume control min value (in 1/256 dB)966 p_volume_max playback volume control max value (in 1/256 dB)967 p_volume_res playback volume control resolution (in 1/256 dB)968 req_number the number of pre-allocated requests for both capture969 and playback970 function_name name of the interface971 p_it_name playback input terminal name972 p_it_ch_name playback channels name973 p_ot_name playback output terminal name974 p_fu_vol_name playback mute/volume functional unit name975 c_it_name capture input terminal name976 c_it_ch_name capture channels name977 c_ot_name capture output terminal name978 c_fu_vol_name capture mute/volume functional unit name979 ================ ====================================================980 981The attributes have sane default values.982 983Testing the UAC1 function984-------------------------985 986device: run the gadget987host: aplay -l # should list our USB Audio Gadget988 989This function does not require real hardware support, it just990sends a stream of audio data to/from the host. In order to991actually hear something at the device side, a command similar992to this must be used at the device side::993 994 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &995 996e.g.::997 998 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \999 aplay -D default:CARD=OdroidU31000 1001 100221. MIDI2 function1003==================1004 1005The function is provided by usb_f_midi2.ko module.1006It will create a virtual ALSA card containing a UMP rawmidi device1007where the UMP packet is looped back. In addition, a legacy rawmidi1008device is created. The UMP rawmidi is bound with ALSA sequencer1009clients, too.1010 1011Function-specific configfs interface1012------------------------------------1013 1014The function name to use when creating the function directory is "midi2".1015The midi2 function provides these attributes in its function directory1016as the card top-level information:1017 1018 ============= =================================================1019 process_ump Bool flag to process UMP Stream messages (0 or 1)1020 static_block Bool flag for static blocks (0 or 1)1021 iface_name Optional interface name string1022 ============= =================================================1023 1024The directory contains a subdirectory "ep.0", and this provides the1025attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints):1026 1027 ============= =================================================1028 protocol_caps MIDI protocol capabilities;1029 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols1030 protocol Default MIDI protocol (either 1 or 2)1031 ep_name UMP Endpoint name string1032 product_id Product ID string1033 manufacturer Manufacture ID number (24 bit)1034 family Device family ID number (16 bit)1035 model Device model ID number (16 bit)1036 sw_revision Software revision (32 bit)1037 ============= =================================================1038 1039Each Endpoint subdirectory contains a subdirectory "block.0", which1040represents the Function Block for Block 0 information.1041Its attributes are:1042 1043 ================= ===============================================1044 name Function Block name string1045 direction Direction of this FB1046 1: input, 2: output, or 3: bidirectional1047 first_group The first UMP Group number (0-15)1048 num_groups The number of groups in this FB (1-16)1049 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15)1050 midi1_num_groups The number of groups for MIDI 1.0 (0-16)1051 ui_hint UI-hint of this FB1052 0: unknown, 1: receiver, 2: sender, 3: both1053 midi_ci_verison Supported MIDI-CI version number (8 bit)1054 is_midi1 Legacy MIDI 1.0 device (0-2)1055 0: MIDI 2.0 device,1056 1: MIDI 1.0 without restriction, or1057 2: MIDI 1.0 with low speed1058 sysex8_streams Max number of SysEx8 streams (8 bit)1059 active Bool flag for FB activity (0 or 1)1060 ================= ===============================================1061 1062If multiple Function Blocks are required, you can add more Function1063Blocks by creating subdirectories "block.<num>" with the corresponding1064Function Block number (1, 2, ....). The FB subdirectories can be1065dynamically removed, too. Note that the Function Block numbers must be1066continuous.1067 1068Similarly, if you multiple UMP Endpoints are required, you can add1069more Endpoints by creating subdirectories "ep.<num>". The number must1070be continuous.1071 1072For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 01073to `process_ump` flag. Then the whole UMP v1.1 requests are ignored.1074 1075Testing the MIDI2 function1076--------------------------1077 1078On the device: run the gadget, and running::1079 1080 $ cat /proc/asound/cards1081 1082will show a new sound card containing a MIDI2 device.1083 1084OTOH, on the host::1085 1086 $ cat /proc/asound/cards1087 1088will show a new sound card containing either MIDI1 or MIDI2 device,1089depending on the USB audio driver configuration.1090 1091On both, when ALSA sequencer is enabled on the host, you can find the1092UMP MIDI client such as "MIDI 2.0 Gadget".1093 1094As the driver simply loops back the data, there is no need for a real1095device just for testing.1096 1097For testing a MIDI input from the gadget to the host (e.g. emulating a1098MIDI keyboard), you can send a MIDI stream like the following.1099 1100On the gadget::1101 1102 $ aconnect -o1103 ....1104 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1]1105 0 'MIDI 2.0 '1106 1 'Group 1 (MIDI 2.0 Gadget I/O)'1107 $ aplaymidi -p 20:1 to_host.mid1108 1109On the host::1110 1111 $ aconnect -i1112 ....1113 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2]1114 0 'MIDI 2.0 '1115 1 'Group 1 (MIDI 2.0 Gadget I/O)'1116 $ arecordmidi -p 24:1 from_gadget.mid1117 1118If you have a UMP-capable application, you can use the UMP port to1119send/receive the raw UMP packets, too. For example, aseqdump program1120with UMP support can receive from UMP port. On the host::1121 1122 $ aseqdump -u 2 -p 24:11123 Waiting for data. Press Ctrl+C to end.1124 Source Group Event Ch Data1125 24:1 Group 0, Program change 0, program 0, Bank select 0:01126 24:1 Group 0, Channel pressure 0, value 0x800000001127 1128For testing a MIDI output to the gadget to the host (e.g. emulating a1129MIDI synth), it'll be just other way round.1130 1131On the gadget::1132 1133 $ arecordmidi -p 20:1 from_host.mid1134 1135On the host::1136 1137 $ aplaymidi -p 24:1 to_gadget.mid1138 1139The access to MIDI 1.0 on altset 0 on the host is supported, and it's1140translated from/to UMP packets on the gadget. It's bound to only1141Function Block 0.1142 1143The current operation mode can be observed in ALSA control element1144"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example::1145 1146 $ amixer -c1 contents1147 numid=1,iface=RAWMIDI,name='Operation Mode'1148 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=01149 : values=21150 1151where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1).1152The example above shows it's running in 2, i.e. MIDI 2.0.1153