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 max_segment_size Segment size required for P2P connections. This 460 will set MTU to 14 bytes 461 ======================= ================================================== 462 463and after creating the functions/ncm.<instance name> they contain default 464values: qmult is 5, dev_addr and host_addr are randomly selected. 465The ifname can be written to if the function is not bound. A write must be an 466interface pattern such as "usb%d", which will cause the net core to choose the 467next free usbX interface. By default, it is set to "usb%d". 468 469Testing the NCM function 470------------------------ 471 472Configure IP addresses of the device and the host. Then: 473 474On the device:: 475 476 ping <host's IP> 477 478On the host:: 479 480 ping <device's IP> 481 48211. OBEX function 483================= 484 485The function is provided by usb_f_obex.ko module. 486 487Function-specific configfs interface 488------------------------------------ 489 490The function name to use when creating the function directory is "obex". 491The OBEX function provides just one attribute in its function directory: 492 493 port_num 494 495The attribute is read-only. 496 497There can be at most 4 ACM/generic serial/OBEX ports in the system. 498 499Testing the OBEX function 500------------------------- 501 502On device:: 503 504 seriald -f /dev/ttyGS<Y> -s 1024 505 506On host:: 507 508 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ 509 -t<out endpoint addr> -r<in endpoint addr> 510 511where seriald and serialc are Felipe's utilities found here: 512 513 https://github.com/felipebalbi/usb-tools.git master 514 51512. PHONET function 516=================== 517 518The function is provided by usb_f_phonet.ko module. 519 520Function-specific configfs interface 521------------------------------------ 522 523The function name to use when creating the function directory is "phonet". 524The PHONET function provides just one attribute in its function directory: 525 526 =============== ================================================== 527 ifname network device interface name associated with this 528 function instance 529 =============== ================================================== 530 531Testing the PHONET function 532--------------------------- 533 534It is not possible to test the SOCK_STREAM protocol without a specific piece 535of hardware, so only SOCK_DGRAM has been tested. For the latter to work, 536in the past I had to apply the patch mentioned here: 537 538http://www.spinics.net/lists/linux-usb/msg85689.html 539 540These tools are required: 541 542git://git.gitorious.org/meego-cellular/phonet-utils.git 543 544On the host:: 545 546 $ ./phonet -a 0x10 -i usbpn0 547 $ ./pnroute add 0x6c usbpn0 548 $./pnroute add 0x10 usbpn0 549 $ ifconfig usbpn0 up 550 551On the device:: 552 553 $ ./phonet -a 0x6c -i upnlink0 554 $ ./pnroute add 0x10 upnlink0 555 $ ifconfig upnlink0 up 556 557Then a test program can be used:: 558 559 http://www.spinics.net/lists/linux-usb/msg85690.html 560 561On the device:: 562 563 $ ./pnxmit -a 0x6c -r 564 565On the host:: 566 567 $ ./pnxmit -a 0x10 -s 0x6c 568 569As a result some data should be sent from host to device. 570Then the other way round: 571 572On the host:: 573 574 $ ./pnxmit -a 0x10 -r 575 576On the device:: 577 578 $ ./pnxmit -a 0x6c -s 0x10 579 58013. RNDIS function 581================== 582 583The function is provided by usb_f_rndis.ko module. 584 585Function-specific configfs interface 586------------------------------------ 587 588The function name to use when creating the function directory is "rndis". 589The RNDIS function provides these attributes in its function directory: 590 591 =============== ================================================== 592 ifname network device interface name associated with this 593 function instance 594 qmult queue length multiplier for high and super speed 595 host_addr MAC address of host's end of this 596 Ethernet over USB link 597 dev_addr MAC address of device's end of this 598 Ethernet over USB link 599 =============== ================================================== 600 601and after creating the functions/rndis.<instance name> they contain default 602values: qmult is 5, dev_addr and host_addr are randomly selected. 603The ifname can be written to if the function is not bound. A write must be an 604interface pattern such as "usb%d", which will cause the net core to choose the 605next free usbX interface. By default, it is set to "usb%d". 606 607Testing the RNDIS function 608-------------------------- 609 610Configure IP addresses of the device and the host. Then: 611 612On the device:: 613 614 ping <host's IP> 615 616On the host:: 617 618 ping <device's IP> 619 62014. SERIAL function 621=================== 622 623The function is provided by usb_f_gser.ko module. 624 625Function-specific configfs interface 626------------------------------------ 627 628The function name to use when creating the function directory is "gser". 629The SERIAL function provides just one attribute in its function directory: 630 631 port_num 632 633The attribute is read-only. 634 635There can be at most 4 ACM/generic serial/OBEX ports in the system. 636 637Testing the SERIAL function 638--------------------------- 639 640On host:: 641 642 insmod usbserial 643 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id 644 645On host:: 646 647 cat > /dev/ttyUSB<X> 648 649On target:: 650 651 cat /dev/ttyGS<Y> 652 653then the other way round 654 655On target:: 656 657 cat > /dev/ttyGS<Y> 658 659On host:: 660 661 cat /dev/ttyUSB<X> 662 66315. SOURCESINK function 664======================= 665 666The function is provided by usb_f_ss_lb.ko module. 667 668Function-specific configfs interface 669------------------------------------ 670 671The function name to use when creating the function directory is "SourceSink". 672The SOURCESINK function provides these attributes in its function directory: 673 674 =============== ================================== 675 pattern 0 (all zeros), 1 (mod63), 2 (none) 676 isoc_interval 1..16 677 isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss) 678 isoc_mult 0..2 (hs/ss only) 679 isoc_maxburst 0..15 (ss only) 680 bulk_buflen buffer length 681 bulk_qlen depth of queue for bulk 682 iso_qlen depth of queue for iso 683 =============== ================================== 684 685Testing the SOURCESINK function 686------------------------------- 687 688device: run the gadget 689 690host: test-usb (tools/usb/testusb.c) 691 692 69316. UAC1 function (legacy implementation) 694========================================= 695 696The function is provided by usb_f_uac1_legacy.ko module. 697 698Function-specific configfs interface 699------------------------------------ 700 701The function name to use when creating the function directory 702is "uac1_legacy". 703The uac1 function provides these attributes in its function directory: 704 705 =============== ==================================== 706 audio_buf_size audio buffer size 707 fn_cap capture pcm device file name 708 fn_cntl control device file name 709 fn_play playback pcm device file name 710 req_buf_size ISO OUT endpoint request buffer size 711 req_count ISO OUT endpoint request count 712 =============== ==================================== 713 714The attributes have sane default values. 715 716Testing the UAC1 function 717------------------------- 718 719device: run the gadget 720 721host:: 722 723 aplay -l # should list our USB Audio Gadget 724 72517. UAC2 function 726================= 727 728The function is provided by usb_f_uac2.ko module. 729 730Function-specific configfs interface 731------------------------------------ 732 733The function name to use when creating the function directory is "uac2". 734The uac2 function provides these attributes in its function directory: 735 736 ================ ==================================================== 737 c_chmask capture channel mask 738 c_srate list of capture sampling rates (comma-separated) 739 c_ssize capture sample size (bytes) 740 c_sync capture synchronization type (async/adaptive) 741 c_mute_present capture mute control enable 742 c_volume_present capture volume control enable 743 c_volume_min capture volume control min value (in 1/256 dB) 744 c_volume_max capture volume control max value (in 1/256 dB) 745 c_volume_res capture volume control resolution (in 1/256 dB) 746 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto) 747 fb_max maximum extra bandwidth in async mode 748 p_chmask playback channel mask 749 p_srate list of playback sampling rates (comma-separated) 750 p_ssize playback sample size (bytes) 751 p_mute_present playback mute control enable 752 p_volume_present playback volume control enable 753 p_volume_min playback volume control min value (in 1/256 dB) 754 p_volume_max playback volume control max value (in 1/256 dB) 755 p_volume_res playback volume control resolution (in 1/256 dB) 756 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto) 757 req_number the number of pre-allocated request for both capture 758 and playback 759 function_name name of the interface 760 c_terminal_type code of the capture terminal type 761 p_terminal_type code of the playback terminal type 762 ================ ==================================================== 763 764The attributes have sane default values. 765 766Testing the UAC2 function 767------------------------- 768 769device: run the gadget 770host: aplay -l # should list our USB Audio Gadget 771 772This function does not require real hardware support, it just 773sends a stream of audio data to/from the host. In order to 774actually hear something at the device side, a command similar 775to this must be used at the device side:: 776 777 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 778 779e.g.:: 780 781 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 782 aplay -D default:CARD=OdroidU3 783 78418. UVC function 785================ 786 787The function is provided by usb_f_uvc.ko module. 788 789Function-specific configfs interface 790------------------------------------ 791 792The function name to use when creating the function directory is "uvc". 793The uvc function provides these attributes in its function directory: 794 795 =================== ================================================ 796 streaming_interval interval for polling endpoint for data transfers 797 streaming_maxburst bMaxBurst for super speed companion descriptor 798 streaming_maxpacket maximum packet size this endpoint is capable of 799 sending or receiving when this configuration is 800 selected 801 function_name name of the interface 802 =================== ================================================ 803 804There are also "control" and "streaming" subdirectories, each of which contain 805a number of their subdirectories. There are some sane defaults provided, but 806the user must provide the following: 807 808 ================== ==================================================== 809 control header create in control/header, link from control/class/fs 810 and/or control/class/ss 811 streaming header create in streaming/header, link from 812 streaming/class/fs and/or streaming/class/hs and/or 813 streaming/class/ss 814 format description create in streaming/mjpeg and/or 815 streaming/uncompressed 816 frame description create in streaming/mjpeg/<format> and/or in 817 streaming/uncompressed/<format> 818 ================== ==================================================== 819 820Each frame description contains frame interval specification, and each 821such specification consists of a number of lines with an interval value 822in each line. The rules stated above are best illustrated with an example:: 823 824 # mkdir functions/uvc.usb0/control/header/h 825 # cd functions/uvc.usb0/control/ 826 # ln -s header/h class/fs 827 # ln -s header/h class/ss 828 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 829 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 830 666666 831 1000000 832 5000000 833 EOF 834 # cd $GADGET_CONFIGFS_ROOT 835 # mkdir functions/uvc.usb0/streaming/header/h 836 # cd functions/uvc.usb0/streaming/header/h 837 # ln -s ../../uncompressed/u 838 # cd ../../class/fs 839 # ln -s ../../header/h 840 # cd ../../class/hs 841 # ln -s ../../header/h 842 # cd ../../class/ss 843 # ln -s ../../header/h 844 845 846Testing the UVC function 847------------------------ 848 849device: run the gadget, modprobe vivid:: 850 851 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 852 853where uvc-gadget is this program: 854 http://git.ideasonboard.org/uvc-gadget.git 855 856with these patches: 857 858 http://www.spinics.net/lists/linux-usb/msg99220.html 859 860host:: 861 862 luvcview -f yuv 863 86419. PRINTER function 865==================== 866 867The function is provided by usb_f_printer.ko module. 868 869Function-specific configfs interface 870------------------------------------ 871 872The function name to use when creating the function directory is "printer". 873The printer function provides these attributes in its function directory: 874 875 ========== =========================================== 876 pnp_string Data to be passed to the host in pnp string 877 q_len Number of requests per endpoint 878 ========== =========================================== 879 880Testing the PRINTER function 881---------------------------- 882 883The most basic testing: 884 885device: run the gadget:: 886 887 # ls -l /devices/virtual/usb_printer_gadget/ 888 889should show g_printer<number>. 890 891If udev is active, then /dev/g_printer<number> should appear automatically. 892 893host: 894 895If udev is active, then e.g. /dev/usb/lp0 should appear. 896 897host->device transmission: 898 899device:: 900 901 # cat /dev/g_printer<number> 902 903host:: 904 905 # cat > /dev/usb/lp0 906 907device->host transmission:: 908 909 # cat > /dev/g_printer<number> 910 911host:: 912 913 # cat /dev/usb/lp0 914 915More advanced testing can be done with the prn_example 916described in Documentation/usb/gadget_printer.rst. 917 918 91920. UAC1 function (virtual ALSA card, using u_audio API) 920======================================================== 921 922The function is provided by usb_f_uac1.ko module. 923It will create a virtual ALSA card and the audio streams are simply 924sinked to and sourced from it. 925 926Function-specific configfs interface 927------------------------------------ 928 929The function name to use when creating the function directory is "uac1". 930The uac1 function provides these attributes in its function directory: 931 932 ================ ==================================================== 933 c_chmask capture channel mask 934 c_srate list of capture sampling rates (comma-separated) 935 c_ssize capture sample size (bytes) 936 c_mute_present capture mute control enable 937 c_volume_present capture volume control enable 938 c_volume_min capture volume control min value (in 1/256 dB) 939 c_volume_max capture volume control max value (in 1/256 dB) 940 c_volume_res capture volume control resolution (in 1/256 dB) 941 p_chmask playback channel mask 942 p_srate list of playback sampling rates (comma-separated) 943 p_ssize playback sample size (bytes) 944 p_mute_present playback mute control enable 945 p_volume_present playback volume control enable 946 p_volume_min playback volume control min value (in 1/256 dB) 947 p_volume_max playback volume control max value (in 1/256 dB) 948 p_volume_res playback volume control resolution (in 1/256 dB) 949 req_number the number of pre-allocated requests for both capture 950 and playback 951 function_name name of the interface 952 ================ ==================================================== 953 954The attributes have sane default values. 955 956Testing the UAC1 function 957------------------------- 958 959device: run the gadget 960host: aplay -l # should list our USB Audio Gadget 961 962This function does not require real hardware support, it just 963sends a stream of audio data to/from the host. In order to 964actually hear something at the device side, a command similar 965to this must be used at the device side:: 966 967 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 968 969e.g.:: 970 971 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 972 aplay -D default:CARD=OdroidU3 973 974 97521. MIDI2 function 976================== 977 978The function is provided by usb_f_midi2.ko module. 979It will create a virtual ALSA card containing a UMP rawmidi device 980where the UMP packet is looped back. In addition, a legacy rawmidi 981device is created. The UMP rawmidi is bound with ALSA sequencer 982clients, too. 983 984Function-specific configfs interface 985------------------------------------ 986 987The function name to use when creating the function directory is "midi2". 988The midi2 function provides these attributes in its function directory 989as the card top-level information: 990 991 ============= ================================================= 992 process_ump Bool flag to process UMP Stream messages (0 or 1) 993 static_block Bool flag for static blocks (0 or 1) 994 iface_name Optional interface name string 995 ============= ================================================= 996 997The directory contains a subdirectory "ep.0", and this provides the 998attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): 999 1000 ============= ================================================= 1001 protocol_caps MIDI protocol capabilities; 1002 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols 1003 protocol Default MIDI protocol (either 1 or 2) 1004 ep_name UMP Endpoint name string 1005 product_id Product ID string 1006 manufacturer Manufacture ID number (24 bit) 1007 family Device family ID number (16 bit) 1008 model Device model ID number (16 bit) 1009 sw_revision Software revision (32 bit) 1010 ============= ================================================= 1011 1012Each Endpoint subdirectory contains a subdirectory "block.0", which 1013represents the Function Block for Block 0 information. 1014Its attributes are: 1015 1016 ================= =============================================== 1017 name Function Block name string 1018 direction Direction of this FB 1019 1: input, 2: output, or 3: bidirectional 1020 first_group The first UMP Group number (0-15) 1021 num_groups The number of groups in this FB (1-16) 1022 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) 1023 midi1_num_groups The number of groups for MIDI 1.0 (0-16) 1024 ui_hint UI-hint of this FB 1025 0: unknown, 1: receiver, 2: sender, 3: both 1026 midi_ci_verison Supported MIDI-CI version number (8 bit) 1027 is_midi1 Legacy MIDI 1.0 device (0-2) 1028 0: MIDI 2.0 device, 1029 1: MIDI 1.0 without restriction, or 1030 2: MIDI 1.0 with low speed 1031 sysex8_streams Max number of SysEx8 streams (8 bit) 1032 active Bool flag for FB activity (0 or 1) 1033 ================= =============================================== 1034 1035If multiple Function Blocks are required, you can add more Function 1036Blocks by creating subdirectories "block.<num>" with the corresponding 1037Function Block number (1, 2, ....). The FB subdirectories can be 1038dynamically removed, too. Note that the Function Block numbers must be 1039continuous. 1040 1041Similarly, if you multiple UMP Endpoints are required, you can add 1042more Endpoints by creating subdirectories "ep.<num>". The number must 1043be continuous. 1044 1045For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 1046to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. 1047 1048Testing the MIDI2 function 1049-------------------------- 1050 1051On the device: run the gadget, and running:: 1052 1053 $ cat /proc/asound/cards 1054 1055will show a new sound card containing a MIDI2 device. 1056 1057OTOH, on the host:: 1058 1059 $ cat /proc/asound/cards 1060 1061will show a new sound card containing either MIDI1 or MIDI2 device, 1062depending on the USB audio driver configuration. 1063 1064On both, when ALSA sequencer is enabled on the host, you can find the 1065UMP MIDI client such as "MIDI 2.0 Gadget". 1066 1067As the driver simply loops back the data, there is no need for a real 1068device just for testing. 1069 1070For testing a MIDI input from the gadget to the host (e.g. emulating a 1071MIDI keyboard), you can send a MIDI stream like the following. 1072 1073On the gadget:: 1074 1075 $ aconnect -o 1076 .... 1077 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 1078 0 'MIDI 2.0 ' 1079 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1080 $ aplaymidi -p 20:1 to_host.mid 1081 1082On the host:: 1083 1084 $ aconnect -i 1085 .... 1086 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 1087 0 'MIDI 2.0 ' 1088 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1089 $ arecordmidi -p 24:1 from_gadget.mid 1090 1091If you have a UMP-capable application, you can use the UMP port to 1092send/receive the raw UMP packets, too. For example, aseqdump program 1093with UMP support can receive from UMP port. On the host:: 1094 1095 $ aseqdump -u 2 -p 24:1 1096 Waiting for data. Press Ctrl+C to end. 1097 Source Group Event Ch Data 1098 24:1 Group 0, Program change 0, program 0, Bank select 0:0 1099 24:1 Group 0, Channel pressure 0, value 0x80000000 1100 1101For testing a MIDI output to the gadget to the host (e.g. emulating a 1102MIDI synth), it'll be just other way round. 1103 1104On the gadget:: 1105 1106 $ arecordmidi -p 20:1 from_host.mid 1107 1108On the host:: 1109 1110 $ aplaymidi -p 24:1 to_gadget.mid 1111 1112The access to MIDI 1.0 on altset 0 on the host is supported, and it's 1113translated from/to UMP packets on the gadget. It's bound to only 1114Function Block 0. 1115 1116The current operation mode can be observed in ALSA control element 1117"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: 1118 1119 $ amixer -c1 contents 1120 numid=1,iface=RAWMIDI,name='Operation Mode' 1121 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 1122 : values=2 1123 1124where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). 1125The example above shows it's running in 2, i.e. MIDI 2.0. 1126