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 c_terminal_type code of the capture terminal type 759 p_terminal_type code of the playback terminal type 760 ================ ==================================================== 761 762The attributes have sane default values. 763 764Testing the UAC2 function 765------------------------- 766 767device: run the gadget 768host: aplay -l # should list our USB Audio Gadget 769 770This function does not require real hardware support, it just 771sends a stream of audio data to/from the host. In order to 772actually hear something at the device side, a command similar 773to this must be used at the device side:: 774 775 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 776 777e.g.:: 778 779 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 780 aplay -D default:CARD=OdroidU3 781 78218. UVC function 783================ 784 785The function is provided by usb_f_uvc.ko module. 786 787Function-specific configfs interface 788------------------------------------ 789 790The function name to use when creating the function directory is "uvc". 791The uvc function provides these attributes in its function directory: 792 793 =================== ================================================ 794 streaming_interval interval for polling endpoint for data transfers 795 streaming_maxburst bMaxBurst for super speed companion descriptor 796 streaming_maxpacket maximum packet size this endpoint is capable of 797 sending or receiving when this configuration is 798 selected 799 function_name name of the interface 800 =================== ================================================ 801 802There are also "control" and "streaming" subdirectories, each of which contain 803a number of their subdirectories. There are some sane defaults provided, but 804the user must provide the following: 805 806 ================== ==================================================== 807 control header create in control/header, link from control/class/fs 808 and/or control/class/ss 809 streaming header create in streaming/header, link from 810 streaming/class/fs and/or streaming/class/hs and/or 811 streaming/class/ss 812 format description create in streaming/mjpeg and/or 813 streaming/uncompressed 814 frame description create in streaming/mjpeg/<format> and/or in 815 streaming/uncompressed/<format> 816 ================== ==================================================== 817 818Each frame description contains frame interval specification, and each 819such specification consists of a number of lines with an interval value 820in each line. The rules stated above are best illustrated with an example:: 821 822 # mkdir functions/uvc.usb0/control/header/h 823 # cd functions/uvc.usb0/control/ 824 # ln -s header/h class/fs 825 # ln -s header/h class/ss 826 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 827 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 828 666666 829 1000000 830 5000000 831 EOF 832 # cd $GADGET_CONFIGFS_ROOT 833 # mkdir functions/uvc.usb0/streaming/header/h 834 # cd functions/uvc.usb0/streaming/header/h 835 # ln -s ../../uncompressed/u 836 # cd ../../class/fs 837 # ln -s ../../header/h 838 # cd ../../class/hs 839 # ln -s ../../header/h 840 # cd ../../class/ss 841 # ln -s ../../header/h 842 843 844Testing the UVC function 845------------------------ 846 847device: run the gadget, modprobe vivid:: 848 849 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 850 851where uvc-gadget is this program: 852 http://git.ideasonboard.org/uvc-gadget.git 853 854with these patches: 855 856 http://www.spinics.net/lists/linux-usb/msg99220.html 857 858host:: 859 860 luvcview -f yuv 861 86219. PRINTER function 863==================== 864 865The function is provided by usb_f_printer.ko module. 866 867Function-specific configfs interface 868------------------------------------ 869 870The function name to use when creating the function directory is "printer". 871The printer function provides these attributes in its function directory: 872 873 ========== =========================================== 874 pnp_string Data to be passed to the host in pnp string 875 q_len Number of requests per endpoint 876 ========== =========================================== 877 878Testing the PRINTER function 879---------------------------- 880 881The most basic testing: 882 883device: run the gadget:: 884 885 # ls -l /devices/virtual/usb_printer_gadget/ 886 887should show g_printer<number>. 888 889If udev is active, then /dev/g_printer<number> should appear automatically. 890 891host: 892 893If udev is active, then e.g. /dev/usb/lp0 should appear. 894 895host->device transmission: 896 897device:: 898 899 # cat /dev/g_printer<number> 900 901host:: 902 903 # cat > /dev/usb/lp0 904 905device->host transmission:: 906 907 # cat > /dev/g_printer<number> 908 909host:: 910 911 # cat /dev/usb/lp0 912 913More advanced testing can be done with the prn_example 914described in Documentation/usb/gadget_printer.rst. 915 916 91720. UAC1 function (virtual ALSA card, using u_audio API) 918======================================================== 919 920The function is provided by usb_f_uac1.ko module. 921It will create a virtual ALSA card and the audio streams are simply 922sinked to and sourced from it. 923 924Function-specific configfs interface 925------------------------------------ 926 927The function name to use when creating the function directory is "uac1". 928The uac1 function provides these attributes in its function directory: 929 930 ================ ==================================================== 931 c_chmask capture channel mask 932 c_srate list of capture sampling rates (comma-separated) 933 c_ssize capture sample size (bytes) 934 c_mute_present capture mute control enable 935 c_volume_present capture volume control enable 936 c_volume_min capture volume control min value (in 1/256 dB) 937 c_volume_max capture volume control max value (in 1/256 dB) 938 c_volume_res capture volume control resolution (in 1/256 dB) 939 p_chmask playback channel mask 940 p_srate list of playback sampling rates (comma-separated) 941 p_ssize playback sample size (bytes) 942 p_mute_present playback mute control enable 943 p_volume_present playback volume control enable 944 p_volume_min playback volume control min value (in 1/256 dB) 945 p_volume_max playback volume control max value (in 1/256 dB) 946 p_volume_res playback volume control resolution (in 1/256 dB) 947 req_number the number of pre-allocated requests for both capture 948 and playback 949 function_name name of the interface 950 ================ ==================================================== 951 952The attributes have sane default values. 953 954Testing the UAC1 function 955------------------------- 956 957device: run the gadget 958host: aplay -l # should list our USB Audio Gadget 959 960This function does not require real hardware support, it just 961sends a stream of audio data to/from the host. In order to 962actually hear something at the device side, a command similar 963to this must be used at the device side:: 964 965 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 966 967e.g.:: 968 969 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 970 aplay -D default:CARD=OdroidU3 971 972 97321. MIDI2 function 974================== 975 976The function is provided by usb_f_midi2.ko module. 977It will create a virtual ALSA card containing a UMP rawmidi device 978where the UMP packet is looped back. In addition, a legacy rawmidi 979device is created. The UMP rawmidi is bound with ALSA sequencer 980clients, too. 981 982Function-specific configfs interface 983------------------------------------ 984 985The function name to use when creating the function directory is "midi2". 986The midi2 function provides these attributes in its function directory 987as the card top-level information: 988 989 ============= ================================================= 990 process_ump Bool flag to process UMP Stream messages (0 or 1) 991 static_block Bool flag for static blocks (0 or 1) 992 iface_name Optional interface name string 993 ============= ================================================= 994 995The directory contains a subdirectory "ep.0", and this provides the 996attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): 997 998 ============= ================================================= 999 protocol_caps MIDI protocol capabilities; 1000 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols 1001 protocol Default MIDI protocol (either 1 or 2) 1002 ep_name UMP Endpoint name string 1003 product_id Product ID string 1004 manufacturer Manufacture ID number (24 bit) 1005 family Device family ID number (16 bit) 1006 model Device model ID number (16 bit) 1007 sw_revision Software revision (32 bit) 1008 ============= ================================================= 1009 1010Each Endpoint subdirectory contains a subdirectory "block.0", which 1011represents the Function Block for Block 0 information. 1012Its attributes are: 1013 1014 ================= =============================================== 1015 name Function Block name string 1016 direction Direction of this FB 1017 1: input, 2: output, or 3: bidirectional 1018 first_group The first UMP Group number (0-15) 1019 num_groups The number of groups in this FB (1-16) 1020 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) 1021 midi1_num_groups The number of groups for MIDI 1.0 (0-16) 1022 ui_hint UI-hint of this FB 1023 0: unknown, 1: receiver, 2: sender, 3: both 1024 midi_ci_verison Supported MIDI-CI version number (8 bit) 1025 is_midi1 Legacy MIDI 1.0 device (0-2) 1026 0: MIDI 2.0 device, 1027 1: MIDI 1.0 without restriction, or 1028 2: MIDI 1.0 with low speed 1029 sysex8_streams Max number of SysEx8 streams (8 bit) 1030 active Bool flag for FB activity (0 or 1) 1031 ================= =============================================== 1032 1033If multiple Function Blocks are required, you can add more Function 1034Blocks by creating subdirectories "block.<num>" with the corresponding 1035Function Block number (1, 2, ....). The FB subdirectories can be 1036dynamically removed, too. Note that the Function Block numbers must be 1037continuous. 1038 1039Similarly, if you multiple UMP Endpoints are required, you can add 1040more Endpoints by creating subdirectories "ep.<num>". The number must 1041be continuous. 1042 1043For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 1044to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. 1045 1046Testing the MIDI2 function 1047-------------------------- 1048 1049On the device: run the gadget, and running:: 1050 1051 $ cat /proc/asound/cards 1052 1053will show a new sound card containing a MIDI2 device. 1054 1055OTOH, on the host:: 1056 1057 $ cat /proc/asound/cards 1058 1059will show a new sound card containing either MIDI1 or MIDI2 device, 1060depending on the USB audio driver configuration. 1061 1062On both, when ALSA sequencer is enabled on the host, you can find the 1063UMP MIDI client such as "MIDI 2.0 Gadget". 1064 1065As the driver simply loops back the data, there is no need for a real 1066device just for testing. 1067 1068For testing a MIDI input from the gadget to the host (e.g. emulating a 1069MIDI keyboard), you can send a MIDI stream like the following. 1070 1071On the gadget:: 1072 1073 $ aconnect -o 1074 .... 1075 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 1076 0 'MIDI 2.0 ' 1077 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1078 $ aplaymidi -p 20:1 to_host.mid 1079 1080On the host:: 1081 1082 $ aconnect -i 1083 .... 1084 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 1085 0 'MIDI 2.0 ' 1086 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1087 $ arecordmidi -p 24:1 from_gadget.mid 1088 1089If you have a UMP-capable application, you can use the UMP port to 1090send/receive the raw UMP packets, too. For example, aseqdump program 1091with UMP support can receive from UMP port. On the host:: 1092 1093 $ aseqdump -u 2 -p 24:1 1094 Waiting for data. Press Ctrl+C to end. 1095 Source Group Event Ch Data 1096 24:1 Group 0, Program change 0, program 0, Bank select 0:0 1097 24:1 Group 0, Channel pressure 0, value 0x80000000 1098 1099For testing a MIDI output to the gadget to the host (e.g. emulating a 1100MIDI synth), it'll be just other way round. 1101 1102On the gadget:: 1103 1104 $ arecordmidi -p 20:1 from_host.mid 1105 1106On the host:: 1107 1108 $ aplaymidi -p 24:1 to_gadget.mid 1109 1110The access to MIDI 1.0 on altset 0 on the host is supported, and it's 1111translated from/to UMP packets on the gadget. It's bound to only 1112Function Block 0. 1113 1114The current operation mode can be observed in ALSA control element 1115"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: 1116 1117 $ amixer -c1 contents 1118 numid=1,iface=RAWMIDI,name='Operation Mode' 1119 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 1120 : values=2 1121 1122where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). 1123The example above shows it's running in 2, i.e. MIDI 2.0. 1124