1============== 2Gadget Testing 3============== 4 5This file summarizes information on basic testing of USB functions 6provided by gadgets. 7 8.. contents 9 10 1. ACM function 11 2. ECM function 12 3. ECM subset function 13 4. EEM function 14 5. FFS function 15 6. HID function 16 7. LOOPBACK function 17 8. MASS STORAGE function 18 9. MIDI function 19 10. NCM function 20 11. OBEX function 21 12. PHONET function 22 13. RNDIS function 23 14. SERIAL function 24 15. SOURCESINK function 25 16. UAC1 function (legacy implementation) 26 17. UAC2 function 27 18. UVC function 28 19. PRINTER function 29 20. UAC1 function (new API) 30 21. MIDI2 function 31 32 331. ACM function 34=============== 35 36The function is provided by usb_f_acm.ko module. 37 38Function-specific configfs interface 39------------------------------------ 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_num 45 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 function 52------------------------ 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 round 63 64On the device:: 65 66 cat > /dev/ttyGS<Y> 67 68On the host:: 69 70 cat /dev/ttyACM<X> 71 722. ECM function 73=============== 74 75The function is provided by usb_f_ecm.ko module. 76 77Function-specific configfs interface 78------------------------------------ 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 this 85 function instance 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 =============== ================================================== 92 93and after creating the functions/ecm.<instance name> they contain default 94values: 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 an 96interface pattern such as "usb%d", which will cause the net core to choose the 97next free usbX interface. By default, it is set to "usb%d". 98 99Testing the ECM function 100------------------------ 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 function 113====================== 114 115The function is provided by usb_f_ecm_subset.ko module. 116 117Function-specific configfs interface 118------------------------------------ 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 this 125 function instance 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 =============== ================================================== 132 133and after creating the functions/ecm.<instance name> they contain default 134values: 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 an 136interface pattern such as "usb%d", which will cause the net core to choose the 137next free usbX interface. By default, it is set to "usb%d". 138 139Testing the ECM subset function 140------------------------------- 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 function 153=============== 154 155The function is provided by usb_f_eem.ko module. 156 157Function-specific configfs interface 158------------------------------------ 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 this 165 function instance 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 =============== ================================================== 172 173and after creating the functions/eem.<instance name> they contain default 174values: 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 an 176interface pattern such as "usb%d", which will cause the net core to choose the 177next free usbX interface. By default, it is set to "usb%d". 178 179Testing the EEM function 180------------------------ 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 function 193=============== 194 195The function is provided by usb_f_fs.ko module. 196 197Function-specific configfs interface 198------------------------------------ 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 FunctionFS 204available in the system. Once a "device" is available, the user should follow 205the standard procedure for using FunctionFS (mount it, run the userspace 206process which implements the function proper). The gadget should be enabled 207by writing a suitable string to usb_gadget/<gadget>/UDC. 208 209Testing the FFS function 210------------------------ 211 212On the device: start the function's userspace daemon, enable the gadget 213 214On the host: use the USB function provided by the device 215 2166. HID function 217=============== 218 219The function is provided by usb_f_hid.ko module. 220 221Function-specific configfs interface 222------------------------------------ 223 224The function name to use when creating the function directory is "hid". 225The HID function provides these attributes in its function directory: 226 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 =============== =========================================== 234 235For a keyboard the protocol and the subclass are 1, the report_length is 8, 236while the report_desc is:: 237 238 $ hd my_report_desc 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...| 243 0000003f 244 245Such a sequence of bytes can be stored to the attribute with echo:: 246 247 $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... 248 249Testing the HID function 250------------------------ 251 252Device: 253 254- create the gadget 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:: 259 260 $ ./hid_gadget_test /dev/hidg0 keyboard 261 262Host: 263 264- observe the keystrokes from the gadget 265 2667. LOOPBACK function 267==================== 268 269The function is provided by usb_f_ss_lb.ko module. 270 271Function-specific configfs interface 272------------------------------------ 273 274The function name to use when creating the function directory is "Loopback". 275The LOOPBACK function provides these attributes in its function directory: 276 277 =============== ======================= 278 qlen depth of loopback queue 279 bulk_buflen buffer length 280 =============== ======================= 281 282Testing the LOOPBACK function 283----------------------------- 284 285device: run the gadget 286 287host: test-usb (tools/usb/testusb.c) 288 2898. MASS STORAGE function 290======================== 291 292The function is provided by usb_f_mass_storage.ko module. 293 294Function-specific configfs interface 295------------------------------------ 296 297The function name to use when creating the function directory is "mass_storage". 298The MASS STORAGE function provides these attributes in its directory: 299files: 300 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 =============== ============================================== 309 310and a default lun.0 directory corresponding to SCSI LUN #0. 311 312A new lun can be added with mkdir:: 313 314 $ mkdir functions/mass_storage.0/partition.5 315 316Lun numbering does not have to be continuous, except for lun #0 which is 317created by default. A maximum of 8 luns can be specified and they all must be 318named following the <name>.<number> scheme. The numbers can be 0..8. 319Probably a good convention is to name the luns "lun.<number>", 320although it is not mandatory. 321 322In each lun directory there are the following attribute files: 323 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 332 being removable. 333 cdrom Flag specifying that LUN shall be reported as 334 being a CD-ROM. 335 nofua Flag specifying that FUA flag 336 in SCSI WRITE(10,12) 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 342 result in ejection. 343 =============== ============================================== 344 345Testing the MASS STORAGE function 346--------------------------------- 347 348device: connect the gadget, enable it 349host: dmesg, see the USB drives appear (if system configured to automatically 350mount) 351 3529. MIDI function 353================ 354 355The function is provided by usb_f_midi.ko module. 356 357Function-specific configfs interface 358------------------------------------ 359 360The function name to use when creating the function directory is "midi". 361The MIDI function provides these attributes in its function directory: 362 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 =============== ==================================== 371 372Testing the MIDI function 373------------------------- 374 375There are two cases: playing a mid from the gadget to 376the host and playing a mid from the host to the gadget. 377 3781) Playing a mid from the gadget to the host: 379 380host:: 381 382 $ arecordmidi -l 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 387 388gadget:: 389 390 $ aplaymidi -l 391 Port Client name Port name 392 20:0 f_midi f_midi 393 394 $ aplaymidi -p 20:0 to_host.mid 395 3962) Playing a mid from the host to the gadget 397 398gadget:: 399 400 $ arecordmidi -l 401 Port Client name Port name 402 20:0 f_midi f_midi 403 404 $ arecordmidi -p 20:0 from_host.mid 405 406host:: 407 408 $ aplaymidi -l 409 Port Client name Port name 410 14:0 Midi Through Midi Through Port-0 411 24:0 MIDI Gadget MIDI Gadget MIDI 1 412 413 $ aplaymidi -p24:0 to_gadget.mid 414 415The from_gadget.mid should sound identical to the to_host.mid. 416 417The from_host.id should sound identical to the to_gadget.mid. 418 419MIDI files can be played to speakers/headphones with e.g. timidity installed:: 420 421 $ aplaymidi -l 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 429 430 $ aplaymidi -p 128:0 file.mid 431 432MIDI ports can be logically connected using the aconnect utility, e.g.:: 433 434 $ aconnect 24:0 128:0 # try it on the host 435 436After the gadget's MIDI port is connected to timidity's MIDI port, 437whatever is played at the gadget side with aplaymidi -l is audible 438in host's speakers/headphones. 439 44010. NCM function 441================ 442 443The function is provided by usb_f_ncm.ko module. 444 445Function-specific configfs interface 446------------------------------------ 447 448The function name to use when creating the function directory is "ncm". 449The NCM function provides these attributes in its function directory: 450 451 =============== ================================================== 452 ifname network device interface name associated with this 453 function instance 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 =============== ================================================== 460 461and after creating the functions/ncm.<instance name> they contain default 462values: qmult is 5, dev_addr and host_addr are randomly selected. 463The ifname can be written to if the function is not bound. A write must be an 464interface pattern such as "usb%d", which will cause the net core to choose the 465next free usbX interface. By default, it is set to "usb%d". 466 467Testing the NCM function 468------------------------ 469 470Configure IP addresses of the device and the host. Then: 471 472On the device:: 473 474 ping <host's IP> 475 476On the host:: 477 478 ping <device's IP> 479 48011. OBEX function 481================= 482 483The function is provided by usb_f_obex.ko module. 484 485Function-specific configfs interface 486------------------------------------ 487 488The function name to use when creating the function directory is "obex". 489The OBEX function provides just one attribute in its function directory: 490 491 port_num 492 493The attribute is read-only. 494 495There can be at most 4 ACM/generic serial/OBEX ports in the system. 496 497Testing the OBEX function 498------------------------- 499 500On device:: 501 502 seriald -f /dev/ttyGS<Y> -s 1024 503 504On host:: 505 506 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ 507 -t<out endpoint addr> -r<in endpoint addr> 508 509where seriald and serialc are Felipe's utilities found here: 510 511 https://github.com/felipebalbi/usb-tools.git master 512 51312. PHONET function 514=================== 515 516The function is provided by usb_f_phonet.ko module. 517 518Function-specific configfs interface 519------------------------------------ 520 521The function name to use when creating the function directory is "phonet". 522The PHONET function provides just one attribute in its function directory: 523 524 =============== ================================================== 525 ifname network device interface name associated with this 526 function instance 527 =============== ================================================== 528 529Testing the PHONET function 530--------------------------- 531 532It is not possible to test the SOCK_STREAM protocol without a specific piece 533of hardware, so only SOCK_DGRAM has been tested. For the latter to work, 534in the past I had to apply the patch mentioned here: 535 536http://www.spinics.net/lists/linux-usb/msg85689.html 537 538These tools are required: 539 540git://git.gitorious.org/meego-cellular/phonet-utils.git 541 542On the host:: 543 544 $ ./phonet -a 0x10 -i usbpn0 545 $ ./pnroute add 0x6c usbpn0 546 $./pnroute add 0x10 usbpn0 547 $ ifconfig usbpn0 up 548 549On the device:: 550 551 $ ./phonet -a 0x6c -i upnlink0 552 $ ./pnroute add 0x10 upnlink0 553 $ ifconfig upnlink0 up 554 555Then a test program can be used:: 556 557 http://www.spinics.net/lists/linux-usb/msg85690.html 558 559On the device:: 560 561 $ ./pnxmit -a 0x6c -r 562 563On the host:: 564 565 $ ./pnxmit -a 0x10 -s 0x6c 566 567As a result some data should be sent from host to device. 568Then the other way round: 569 570On the host:: 571 572 $ ./pnxmit -a 0x10 -r 573 574On the device:: 575 576 $ ./pnxmit -a 0x6c -s 0x10 577 57813. RNDIS function 579================== 580 581The function is provided by usb_f_rndis.ko module. 582 583Function-specific configfs interface 584------------------------------------ 585 586The function name to use when creating the function directory is "rndis". 587The RNDIS function provides these attributes in its function directory: 588 589 =============== ================================================== 590 ifname network device interface name associated with this 591 function instance 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 =============== ================================================== 598 599and after creating the functions/rndis.<instance name> they contain default 600values: qmult is 5, dev_addr and host_addr are randomly selected. 601The ifname can be written to if the function is not bound. A write must be an 602interface pattern such as "usb%d", which will cause the net core to choose the 603next free usbX interface. By default, it is set to "usb%d". 604 605Testing the RNDIS function 606-------------------------- 607 608Configure IP addresses of the device and the host. Then: 609 610On the device:: 611 612 ping <host's IP> 613 614On the host:: 615 616 ping <device's IP> 617 61814. SERIAL function 619=================== 620 621The function is provided by usb_f_gser.ko module. 622 623Function-specific configfs interface 624------------------------------------ 625 626The function name to use when creating the function directory is "gser". 627The SERIAL function provides just one attribute in its function directory: 628 629 port_num 630 631The attribute is read-only. 632 633There can be at most 4 ACM/generic serial/OBEX ports in the system. 634 635Testing the SERIAL function 636--------------------------- 637 638On host:: 639 640 insmod usbserial 641 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id 642 643On host:: 644 645 cat > /dev/ttyUSB<X> 646 647On target:: 648 649 cat /dev/ttyGS<Y> 650 651then the other way round 652 653On target:: 654 655 cat > /dev/ttyGS<Y> 656 657On host:: 658 659 cat /dev/ttyUSB<X> 660 66115. SOURCESINK function 662======================= 663 664The function is provided by usb_f_ss_lb.ko module. 665 666Function-specific configfs interface 667------------------------------------ 668 669The function name to use when creating the function directory is "SourceSink". 670The SOURCESINK function provides these attributes in its function directory: 671 672 =============== ================================== 673 pattern 0 (all zeros), 1 (mod63), 2 (none) 674 isoc_interval 1..16 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 =============== ================================== 682 683Testing the SOURCESINK function 684------------------------------- 685 686device: run the gadget 687 688host: test-usb (tools/usb/testusb.c) 689 690 69116. UAC1 function (legacy implementation) 692========================================= 693 694The function is provided by usb_f_uac1_legacy.ko module. 695 696Function-specific configfs interface 697------------------------------------ 698 699The function name to use when creating the function directory 700is "uac1_legacy". 701The uac1 function provides these attributes in its function directory: 702 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 =============== ==================================== 711 712The attributes have sane default values. 713 714Testing the UAC1 function 715------------------------- 716 717device: run the gadget 718 719host:: 720 721 aplay -l # should list our USB Audio Gadget 722 72317. UAC2 function 724================= 725 726The function is provided by usb_f_uac2.ko module. 727 728Function-specific configfs interface 729------------------------------------ 730 731The function name to use when creating the function directory is "uac2". 732The uac2 function provides these attributes in its function directory: 733 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 756 and playback 757 function_name name of the interface 758 ================ ==================================================== 759 760The attributes have sane default values. 761 762Testing the UAC2 function 763------------------------- 764 765device: run the gadget 766host: aplay -l # should list our USB Audio Gadget 767 768This function does not require real hardware support, it just 769sends a stream of audio data to/from the host. In order to 770actually hear something at the device side, a command similar 771to this must be used at the device side:: 772 773 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 774 775e.g.:: 776 777 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 778 aplay -D default:CARD=OdroidU3 779 78018. UVC function 781================ 782 783The function is provided by usb_f_uvc.ko module. 784 785Function-specific configfs interface 786------------------------------------ 787 788The function name to use when creating the function directory is "uvc". 789The uvc function provides these attributes in its function directory: 790 791 =================== ================================================ 792 streaming_interval interval for polling endpoint for data transfers 793 streaming_maxburst bMaxBurst for super speed companion descriptor 794 streaming_maxpacket maximum packet size this endpoint is capable of 795 sending or receiving when this configuration is 796 selected 797 function_name name of the interface 798 =================== ================================================ 799 800There are also "control" and "streaming" subdirectories, each of which contain 801a number of their subdirectories. There are some sane defaults provided, but 802the user must provide the following: 803 804 ================== ==================================================== 805 control header create in control/header, link from control/class/fs 806 and/or control/class/ss 807 streaming header create in streaming/header, link from 808 streaming/class/fs and/or streaming/class/hs and/or 809 streaming/class/ss 810 format description create in streaming/mjpeg and/or 811 streaming/uncompressed 812 frame description create in streaming/mjpeg/<format> and/or in 813 streaming/uncompressed/<format> 814 ================== ==================================================== 815 816Each frame description contains frame interval specification, and each 817such specification consists of a number of lines with an interval value 818in each line. The rules stated above are best illustrated with an example:: 819 820 # mkdir functions/uvc.usb0/control/header/h 821 # cd functions/uvc.usb0/control/ 822 # ln -s header/h class/fs 823 # ln -s header/h class/ss 824 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 825 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 826 666666 827 1000000 828 5000000 829 EOF 830 # cd $GADGET_CONFIGFS_ROOT 831 # mkdir functions/uvc.usb0/streaming/header/h 832 # cd functions/uvc.usb0/streaming/header/h 833 # ln -s ../../uncompressed/u 834 # cd ../../class/fs 835 # ln -s ../../header/h 836 # cd ../../class/hs 837 # ln -s ../../header/h 838 # cd ../../class/ss 839 # ln -s ../../header/h 840 841 842Testing the UVC function 843------------------------ 844 845device: run the gadget, modprobe vivid:: 846 847 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 848 849where uvc-gadget is this program: 850 http://git.ideasonboard.org/uvc-gadget.git 851 852with these patches: 853 854 http://www.spinics.net/lists/linux-usb/msg99220.html 855 856host:: 857 858 luvcview -f yuv 859 86019. PRINTER function 861==================== 862 863The function is provided by usb_f_printer.ko module. 864 865Function-specific configfs interface 866------------------------------------ 867 868The function name to use when creating the function directory is "printer". 869The printer function provides these attributes in its function directory: 870 871 ========== =========================================== 872 pnp_string Data to be passed to the host in pnp string 873 q_len Number of requests per endpoint 874 ========== =========================================== 875 876Testing the PRINTER function 877---------------------------- 878 879The most basic testing: 880 881device: run the gadget:: 882 883 # ls -l /devices/virtual/usb_printer_gadget/ 884 885should show g_printer<number>. 886 887If udev is active, then /dev/g_printer<number> should appear automatically. 888 889host: 890 891If udev is active, then e.g. /dev/usb/lp0 should appear. 892 893host->device transmission: 894 895device:: 896 897 # cat /dev/g_printer<number> 898 899host:: 900 901 # cat > /dev/usb/lp0 902 903device->host transmission:: 904 905 # cat > /dev/g_printer<number> 906 907host:: 908 909 # cat /dev/usb/lp0 910 911More advanced testing can be done with the prn_example 912described in Documentation/usb/gadget_printer.rst. 913 914 91520. UAC1 function (virtual ALSA card, using u_audio API) 916======================================================== 917 918The function is provided by usb_f_uac1.ko module. 919It will create a virtual ALSA card and the audio streams are simply 920sinked to and sourced from it. 921 922Function-specific configfs interface 923------------------------------------ 924 925The function name to use when creating the function directory is "uac1". 926The uac1 function provides these attributes in its function directory: 927 928 ================ ==================================================== 929 c_chmask capture channel mask 930 c_srate list of capture sampling rates (comma-separated) 931 c_ssize capture sample size (bytes) 932 c_mute_present capture mute control enable 933 c_volume_present capture volume control enable 934 c_volume_min capture volume control min value (in 1/256 dB) 935 c_volume_max capture volume control max value (in 1/256 dB) 936 c_volume_res capture volume control resolution (in 1/256 dB) 937 p_chmask playback channel mask 938 p_srate list of playback sampling rates (comma-separated) 939 p_ssize playback sample size (bytes) 940 p_mute_present playback mute control enable 941 p_volume_present playback volume control enable 942 p_volume_min playback volume control min value (in 1/256 dB) 943 p_volume_max playback volume control max value (in 1/256 dB) 944 p_volume_res playback volume control resolution (in 1/256 dB) 945 req_number the number of pre-allocated requests for both capture 946 and playback 947 function_name name of the interface 948 ================ ==================================================== 949 950The attributes have sane default values. 951 952Testing the UAC1 function 953------------------------- 954 955device: run the gadget 956host: aplay -l # should list our USB Audio Gadget 957 958This function does not require real hardware support, it just 959sends a stream of audio data to/from the host. In order to 960actually hear something at the device side, a command similar 961to this must be used at the device side:: 962 963 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 964 965e.g.:: 966 967 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 968 aplay -D default:CARD=OdroidU3 969 970 97121. MIDI2 function 972================== 973 974The function is provided by usb_f_midi2.ko module. 975It will create a virtual ALSA card containing a UMP rawmidi device 976where the UMP packet is looped back. In addition, a legacy rawmidi 977device is created. The UMP rawmidi is bound with ALSA sequencer 978clients, too. 979 980Function-specific configfs interface 981------------------------------------ 982 983The function name to use when creating the function directory is "midi2". 984The midi2 function provides these attributes in its function directory 985as the card top-level information: 986 987 ============= ================================================= 988 process_ump Bool flag to process UMP Stream messages (0 or 1) 989 static_block Bool flag for static blocks (0 or 1) 990 iface_name Optional interface name string 991 ============= ================================================= 992 993The directory contains a subdirectory "ep.0", and this provides the 994attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): 995 996 ============= ================================================= 997 protocol_caps MIDI protocol capabilities; 998 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols 999 protocol Default MIDI protocol (either 1 or 2) 1000 ep_name UMP Endpoint name string 1001 product_id Product ID string 1002 manufacturer Manufacture ID number (24 bit) 1003 family Device family ID number (16 bit) 1004 model Device model ID number (16 bit) 1005 sw_revision Software revision (32 bit) 1006 ============= ================================================= 1007 1008Each Endpoint subdirectory contains a subdirectory "block.0", which 1009represents the Function Block for Block 0 information. 1010Its attributes are: 1011 1012 ================= =============================================== 1013 name Function Block name string 1014 direction Direction of this FB 1015 1: input, 2: output, or 3: bidirectional 1016 first_group The first UMP Group number (0-15) 1017 num_groups The number of groups in this FB (1-16) 1018 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) 1019 midi1_num_groups The number of groups for MIDI 1.0 (0-16) 1020 ui_hint UI-hint of this FB 1021 0: unknown, 1: receiver, 2: sender, 3: both 1022 midi_ci_verison Supported MIDI-CI version number (8 bit) 1023 is_midi1 Legacy MIDI 1.0 device (0-2) 1024 0: MIDI 2.0 device, 1025 1: MIDI 1.0 without restriction, or 1026 2: MIDI 1.0 with low speed 1027 sysex8_streams Max number of SysEx8 streams (8 bit) 1028 active Bool flag for FB activity (0 or 1) 1029 ================= =============================================== 1030 1031If multiple Function Blocks are required, you can add more Function 1032Blocks by creating subdirectories "block.<num>" with the corresponding 1033Function Block number (1, 2, ....). The FB subdirectories can be 1034dynamically removed, too. Note that the Function Block numbers must be 1035continuous. 1036 1037Similarly, if you multiple UMP Endpoints are required, you can add 1038more Endpoints by creating subdirectories "ep.<num>". The number must 1039be continuous. 1040 1041For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 1042to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. 1043 1044Testing the MIDI2 function 1045-------------------------- 1046 1047On the device: run the gadget, and running:: 1048 1049 $ cat /proc/asound/cards 1050 1051will show a new sound card containing a MIDI2 device. 1052 1053OTOH, on the host:: 1054 1055 $ cat /proc/asound/cards 1056 1057will show a new sound card containing either MIDI1 or MIDI2 device, 1058depending on the USB audio driver configuration. 1059 1060On both, when ALSA sequencer is enabled on the host, you can find the 1061UMP MIDI client such as "MIDI 2.0 Gadget". 1062 1063As the driver simply loops back the data, there is no need for a real 1064device just for testing. 1065 1066For testing a MIDI input from the gadget to the host (e.g. emulating a 1067MIDI keyboard), you can send a MIDI stream like the following. 1068 1069On the gadget:: 1070 1071 $ aconnect -o 1072 .... 1073 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 1074 0 'MIDI 2.0 ' 1075 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1076 $ aplaymidi -p 20:1 to_host.mid 1077 1078On the host:: 1079 1080 $ aconnect -i 1081 .... 1082 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 1083 0 'MIDI 2.0 ' 1084 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1085 $ arecordmidi -p 24:1 from_gadget.mid 1086 1087If you have a UMP-capable application, you can use the UMP port to 1088send/receive the raw UMP packets, too. For example, aseqdump program 1089with UMP support can receive from UMP port. On the host:: 1090 1091 $ aseqdump -u 2 -p 24:1 1092 Waiting for data. Press Ctrl+C to end. 1093 Source Group Event Ch Data 1094 24:1 Group 0, Program change 0, program 0, Bank select 0:0 1095 24:1 Group 0, Channel pressure 0, value 0x80000000 1096 1097For testing a MIDI output to the gadget to the host (e.g. emulating a 1098MIDI synth), it'll be just other way round. 1099 1100On the gadget:: 1101 1102 $ arecordmidi -p 20:1 from_host.mid 1103 1104On the host:: 1105 1106 $ aplaymidi -p 24:1 to_gadget.mid 1107 1108The access to MIDI 1.0 on altset 0 on the host is supported, and it's 1109translated from/to UMP packets on the gadget. It's bound to only 1110Function Block 0. 1111 1112The current operation mode can be observed in ALSA control element 1113"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: 1114 1115 $ amixer -c1 contents 1116 numid=1,iface=RAWMIDI,name='Operation Mode' 1117 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 1118 : values=2 1119 1120where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). 1121The example above shows it's running in 2, i.e. MIDI 2.0. 1122