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 209The FFS function provides just one attribute in its function directory: 210 211 ready 212 213The attribute is read-only and signals if the function is ready (1) to be 214used, E.G. if userspace has written descriptors and strings to ep0, so 215the gadget can be enabled. 216 217Testing the FFS function 218------------------------ 219 220On the device: start the function's userspace daemon, enable the gadget 221 222On the host: use the USB function provided by the device 223 2246. HID function 225=============== 226 227The function is provided by usb_f_hid.ko module. 228 229Function-specific configfs interface 230------------------------------------ 231 232The function name to use when creating the function directory is "hid". 233The HID function provides these attributes in its function directory: 234 235 =============== =========================================== 236 protocol HID protocol to use 237 report_desc data to be used in HID reports, except data 238 passed with /dev/hidg<X> 239 report_length HID report length 240 subclass HID subclass to use 241 =============== =========================================== 242 243For a keyboard the protocol and the subclass are 1, the report_length is 8, 244while the report_desc is:: 245 246 $ hd my_report_desc 247 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| 248 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| 249 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| 250 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| 251 0000003f 252 253Such a sequence of bytes can be stored to the attribute with echo:: 254 255 $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... 256 257Testing the HID function 258------------------------ 259 260Device: 261 262- create the gadget 263- connect the gadget to a host, preferably not the one used 264 to control the gadget 265- run a program which writes to /dev/hidg<N>, e.g. 266 a userspace program found in Documentation/usb/gadget_hid.rst:: 267 268 $ ./hid_gadget_test /dev/hidg0 keyboard 269 270Host: 271 272- observe the keystrokes from the gadget 273 2747. LOOPBACK function 275==================== 276 277The function is provided by usb_f_ss_lb.ko module. 278 279Function-specific configfs interface 280------------------------------------ 281 282The function name to use when creating the function directory is "Loopback". 283The LOOPBACK function provides these attributes in its function directory: 284 285 =============== ======================= 286 qlen depth of loopback queue 287 bulk_buflen buffer length 288 =============== ======================= 289 290Testing the LOOPBACK function 291----------------------------- 292 293device: run the gadget 294 295host: test-usb (tools/usb/testusb.c) 296 2978. MASS STORAGE function 298======================== 299 300The function is provided by usb_f_mass_storage.ko module. 301 302Function-specific configfs interface 303------------------------------------ 304 305The function name to use when creating the function directory is "mass_storage". 306The MASS STORAGE function provides these attributes in its directory: 307files: 308 309 =============== ============================================== 310 stall Set to permit function to halt bulk endpoints. 311 Disabled on some USB devices known not to work 312 correctly. You should set it to true. 313 num_buffers Number of pipeline buffers. Valid numbers 314 are 2..4. Available only if 315 CONFIG_USB_GADGET_DEBUG_FILES is set. 316 =============== ============================================== 317 318and a default lun.0 directory corresponding to SCSI LUN #0. 319 320A new lun can be added with mkdir:: 321 322 $ mkdir functions/mass_storage.0/partition.5 323 324Lun numbering does not have to be continuous, except for lun #0 which is 325created by default. A maximum of 8 luns can be specified and they all must be 326named following the <name>.<number> scheme. The numbers can be 0..8. 327Probably a good convention is to name the luns "lun.<number>", 328although it is not mandatory. 329 330In each lun directory there are the following attribute files: 331 332 =============== ============================================== 333 file The path to the backing file for the LUN. 334 Required if LUN is not marked as removable. 335 ro Flag specifying access to the LUN shall be 336 read-only. This is implied if CD-ROM emulation 337 is enabled as well as when it was impossible 338 to open "filename" in R/W mode. 339 removable Flag specifying that LUN shall be indicated as 340 being removable. 341 cdrom Flag specifying that LUN shall be reported as 342 being a CD-ROM. 343 nofua Flag specifying that FUA flag 344 in SCSI WRITE(10,12) 345 forced_eject This write-only file is useful only when 346 the function is active. It causes the backing 347 file to be forcibly detached from the LUN, 348 regardless of whether the host has allowed it. 349 Any non-zero number of bytes written will 350 result in ejection. 351 =============== ============================================== 352 353Testing the MASS STORAGE function 354--------------------------------- 355 356device: connect the gadget, enable it 357host: dmesg, see the USB drives appear (if system configured to automatically 358mount) 359 3609. MIDI function 361================ 362 363The function is provided by usb_f_midi.ko module. 364 365Function-specific configfs interface 366------------------------------------ 367 368The function name to use when creating the function directory is "midi". 369The MIDI function provides these attributes in its function directory: 370 371 =============== ==================================== 372 buflen MIDI buffer length 373 id ID string for the USB MIDI adapter 374 in_ports number of MIDI input ports 375 index index value for the USB MIDI adapter 376 out_ports number of MIDI output ports 377 qlen USB read request queue length 378 =============== ==================================== 379 380Testing the MIDI function 381------------------------- 382 383There are two cases: playing a mid from the gadget to 384the host and playing a mid from the host to the gadget. 385 3861) Playing a mid from the gadget to the host: 387 388host:: 389 390 $ arecordmidi -l 391 Port Client name Port name 392 14:0 Midi Through Midi Through Port-0 393 24:0 MIDI Gadget MIDI Gadget MIDI 1 394 $ arecordmidi -p 24:0 from_gadget.mid 395 396gadget:: 397 398 $ aplaymidi -l 399 Port Client name Port name 400 20:0 f_midi f_midi 401 402 $ aplaymidi -p 20:0 to_host.mid 403 4042) Playing a mid from the host to the gadget 405 406gadget:: 407 408 $ arecordmidi -l 409 Port Client name Port name 410 20:0 f_midi f_midi 411 412 $ arecordmidi -p 20:0 from_host.mid 413 414host:: 415 416 $ aplaymidi -l 417 Port Client name Port name 418 14:0 Midi Through Midi Through Port-0 419 24:0 MIDI Gadget MIDI Gadget MIDI 1 420 421 $ aplaymidi -p24:0 to_gadget.mid 422 423The from_gadget.mid should sound identical to the to_host.mid. 424 425The from_host.id should sound identical to the to_gadget.mid. 426 427MIDI files can be played to speakers/headphones with e.g. timidity installed:: 428 429 $ aplaymidi -l 430 Port Client name Port name 431 14:0 Midi Through Midi Through Port-0 432 24:0 MIDI Gadget MIDI Gadget MIDI 1 433 128:0 TiMidity TiMidity port 0 434 128:1 TiMidity TiMidity port 1 435 128:2 TiMidity TiMidity port 2 436 128:3 TiMidity TiMidity port 3 437 438 $ aplaymidi -p 128:0 file.mid 439 440MIDI ports can be logically connected using the aconnect utility, e.g.:: 441 442 $ aconnect 24:0 128:0 # try it on the host 443 444After the gadget's MIDI port is connected to timidity's MIDI port, 445whatever is played at the gadget side with aplaymidi -l is audible 446in host's speakers/headphones. 447 44810. NCM function 449================ 450 451The function is provided by usb_f_ncm.ko module. 452 453Function-specific configfs interface 454------------------------------------ 455 456The function name to use when creating the function directory is "ncm". 457The NCM function provides these attributes in its function directory: 458 459 ======================= ================================================== 460 ifname network device interface name associated with this 461 function instance 462 qmult queue length multiplier for high and super speed 463 host_addr MAC address of host's end of this 464 Ethernet over USB link 465 dev_addr MAC address of device's end of this 466 Ethernet over USB link 467 max_segment_size Segment size required for P2P connections. This 468 will set MTU to 14 bytes 469 ======================= ================================================== 470 471and after creating the functions/ncm.<instance name> they contain default 472values: qmult is 5, dev_addr and host_addr are randomly selected. 473The ifname can be written to if the function is not bound. A write must be an 474interface pattern such as "usb%d", which will cause the net core to choose the 475next free usbX interface. By default, it is set to "usb%d". 476 477Testing the NCM function 478------------------------ 479 480Configure IP addresses of the device and the host. Then: 481 482On the device:: 483 484 ping <host's IP> 485 486On the host:: 487 488 ping <device's IP> 489 49011. OBEX function 491================= 492 493The function is provided by usb_f_obex.ko module. 494 495Function-specific configfs interface 496------------------------------------ 497 498The function name to use when creating the function directory is "obex". 499The OBEX function provides just one attribute in its function directory: 500 501 port_num 502 503The attribute is read-only. 504 505There can be at most 4 ACM/generic serial/OBEX ports in the system. 506 507Testing the OBEX function 508------------------------- 509 510On device:: 511 512 seriald -f /dev/ttyGS<Y> -s 1024 513 514On host:: 515 516 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ 517 -t<out endpoint addr> -r<in endpoint addr> 518 519where seriald and serialc are Felipe's utilities found here: 520 521 https://github.com/felipebalbi/usb-tools.git master 522 52312. PHONET function 524=================== 525 526The function is provided by usb_f_phonet.ko module. 527 528Function-specific configfs interface 529------------------------------------ 530 531The function name to use when creating the function directory is "phonet". 532The PHONET function provides just one attribute in its function directory: 533 534 =============== ================================================== 535 ifname network device interface name associated with this 536 function instance 537 =============== ================================================== 538 539Testing the PHONET function 540--------------------------- 541 542It is not possible to test the SOCK_STREAM protocol without a specific piece 543of hardware, so only SOCK_DGRAM has been tested. For the latter to work, 544in the past I had to apply the patch mentioned here: 545 546http://www.spinics.net/lists/linux-usb/msg85689.html 547 548These tools are required: 549 550git://git.gitorious.org/meego-cellular/phonet-utils.git 551 552On the host:: 553 554 $ ./phonet -a 0x10 -i usbpn0 555 $ ./pnroute add 0x6c usbpn0 556 $./pnroute add 0x10 usbpn0 557 $ ifconfig usbpn0 up 558 559On the device:: 560 561 $ ./phonet -a 0x6c -i upnlink0 562 $ ./pnroute add 0x10 upnlink0 563 $ ifconfig upnlink0 up 564 565Then a test program can be used:: 566 567 http://www.spinics.net/lists/linux-usb/msg85690.html 568 569On the device:: 570 571 $ ./pnxmit -a 0x6c -r 572 573On the host:: 574 575 $ ./pnxmit -a 0x10 -s 0x6c 576 577As a result some data should be sent from host to device. 578Then the other way round: 579 580On the host:: 581 582 $ ./pnxmit -a 0x10 -r 583 584On the device:: 585 586 $ ./pnxmit -a 0x6c -s 0x10 587 58813. RNDIS function 589================== 590 591The function is provided by usb_f_rndis.ko module. 592 593Function-specific configfs interface 594------------------------------------ 595 596The function name to use when creating the function directory is "rndis". 597The RNDIS function provides these attributes in its function directory: 598 599 =============== ================================================== 600 ifname network device interface name associated with this 601 function instance 602 qmult queue length multiplier for high and super speed 603 host_addr MAC address of host's end of this 604 Ethernet over USB link 605 dev_addr MAC address of device's end of this 606 Ethernet over USB link 607 =============== ================================================== 608 609and after creating the functions/rndis.<instance name> they contain default 610values: qmult is 5, dev_addr and host_addr are randomly selected. 611The ifname can be written to if the function is not bound. A write must be an 612interface pattern such as "usb%d", which will cause the net core to choose the 613next free usbX interface. By default, it is set to "usb%d". 614 615Testing the RNDIS function 616-------------------------- 617 618Configure IP addresses of the device and the host. Then: 619 620On the device:: 621 622 ping <host's IP> 623 624On the host:: 625 626 ping <device's IP> 627 62814. SERIAL function 629=================== 630 631The function is provided by usb_f_gser.ko module. 632 633Function-specific configfs interface 634------------------------------------ 635 636The function name to use when creating the function directory is "gser". 637The SERIAL function provides just one attribute in its function directory: 638 639 port_num 640 641The attribute is read-only. 642 643There can be at most 4 ACM/generic serial/OBEX ports in the system. 644 645Testing the SERIAL function 646--------------------------- 647 648On host:: 649 650 insmod usbserial 651 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id 652 653On host:: 654 655 cat > /dev/ttyUSB<X> 656 657On target:: 658 659 cat /dev/ttyGS<Y> 660 661then the other way round 662 663On target:: 664 665 cat > /dev/ttyGS<Y> 666 667On host:: 668 669 cat /dev/ttyUSB<X> 670 67115. SOURCESINK function 672======================= 673 674The function is provided by usb_f_ss_lb.ko module. 675 676Function-specific configfs interface 677------------------------------------ 678 679The function name to use when creating the function directory is "SourceSink". 680The SOURCESINK function provides these attributes in its function directory: 681 682 =============== ================================== 683 pattern 0 (all zeros), 1 (mod63), 2 (none) 684 isoc_interval 1..16 685 isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss) 686 isoc_mult 0..2 (hs/ss only) 687 isoc_maxburst 0..15 (ss only) 688 bulk_buflen buffer length 689 bulk_qlen depth of queue for bulk 690 iso_qlen depth of queue for iso 691 =============== ================================== 692 693Testing the SOURCESINK function 694------------------------------- 695 696device: run the gadget 697 698host: test-usb (tools/usb/testusb.c) 699 700 70116. UAC1 function (legacy implementation) 702========================================= 703 704The function is provided by usb_f_uac1_legacy.ko module. 705 706Function-specific configfs interface 707------------------------------------ 708 709The function name to use when creating the function directory 710is "uac1_legacy". 711The uac1 function provides these attributes in its function directory: 712 713 =============== ==================================== 714 audio_buf_size audio buffer size 715 fn_cap capture pcm device file name 716 fn_cntl control device file name 717 fn_play playback pcm device file name 718 req_buf_size ISO OUT endpoint request buffer size 719 req_count ISO OUT endpoint request count 720 =============== ==================================== 721 722The attributes have sane default values. 723 724Testing the UAC1 function 725------------------------- 726 727device: run the gadget 728 729host:: 730 731 aplay -l # should list our USB Audio Gadget 732 73317. UAC2 function 734================= 735 736The function is provided by usb_f_uac2.ko module. 737 738Function-specific configfs interface 739------------------------------------ 740 741The function name to use when creating the function directory is "uac2". 742The uac2 function provides these attributes in its function directory: 743 744 ================ ==================================================== 745 c_chmask capture channel mask 746 c_srate list of capture sampling rates (comma-separated) 747 c_ssize capture sample size (bytes) 748 c_sync capture synchronization type (async/adaptive) 749 c_mute_present capture mute control enable 750 c_volume_present capture volume control enable 751 c_volume_min capture volume control min value (in 1/256 dB) 752 c_volume_max capture volume control max value (in 1/256 dB) 753 c_volume_res capture volume control resolution (in 1/256 dB) 754 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto) 755 fb_max maximum extra bandwidth in async mode 756 p_chmask playback channel mask 757 p_srate list of playback sampling rates (comma-separated) 758 p_ssize playback sample size (bytes) 759 p_mute_present playback mute control enable 760 p_volume_present playback volume control enable 761 p_volume_min playback volume control min value (in 1/256 dB) 762 p_volume_max playback volume control max value (in 1/256 dB) 763 p_volume_res playback volume control resolution (in 1/256 dB) 764 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto) 765 req_number the number of pre-allocated request for both capture 766 and playback 767 function_name name of the interface 768 c_terminal_type code of the capture terminal type 769 p_terminal_type code of the playback terminal type 770 ================ ==================================================== 771 772The attributes have sane default values. 773 774Testing the UAC2 function 775------------------------- 776 777device: run the gadget 778host: aplay -l # should list our USB Audio Gadget 779 780This function does not require real hardware support, it just 781sends a stream of audio data to/from the host. In order to 782actually hear something at the device side, a command similar 783to this must be used at the device side:: 784 785 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 786 787e.g.:: 788 789 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 790 aplay -D default:CARD=OdroidU3 791 79218. UVC function 793================ 794 795The function is provided by usb_f_uvc.ko module. 796 797Function-specific configfs interface 798------------------------------------ 799 800The function name to use when creating the function directory is "uvc". 801The uvc function provides these attributes in its function directory: 802 803 =================== ================================================ 804 streaming_interval interval for polling endpoint for data transfers 805 streaming_maxburst bMaxBurst for super speed companion descriptor 806 streaming_maxpacket maximum packet size this endpoint is capable of 807 sending or receiving when this configuration is 808 selected 809 function_name name of the interface 810 =================== ================================================ 811 812There are also "control" and "streaming" subdirectories, each of which contain 813a number of their subdirectories. There are some sane defaults provided, but 814the user must provide the following: 815 816 ================== ==================================================== 817 control header create in control/header, link from control/class/fs 818 and/or control/class/ss 819 streaming header create in streaming/header, link from 820 streaming/class/fs and/or streaming/class/hs and/or 821 streaming/class/ss 822 format description create in streaming/mjpeg and/or 823 streaming/uncompressed 824 frame description create in streaming/mjpeg/<format> and/or in 825 streaming/uncompressed/<format> 826 ================== ==================================================== 827 828Each frame description contains frame interval specification, and each 829such specification consists of a number of lines with an interval value 830in each line. The rules stated above are best illustrated with an example:: 831 832 # mkdir functions/uvc.usb0/control/header/h 833 # cd functions/uvc.usb0/control/ 834 # ln -s header/h class/fs 835 # ln -s header/h class/ss 836 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 837 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 838 666666 839 1000000 840 5000000 841 EOF 842 # cd $GADGET_CONFIGFS_ROOT 843 # mkdir functions/uvc.usb0/streaming/header/h 844 # cd functions/uvc.usb0/streaming/header/h 845 # ln -s ../../uncompressed/u 846 # cd ../../class/fs 847 # ln -s ../../header/h 848 # cd ../../class/hs 849 # ln -s ../../header/h 850 # cd ../../class/ss 851 # ln -s ../../header/h 852 853 854Testing the UVC function 855------------------------ 856 857device: run the gadget, modprobe vivid:: 858 859 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 860 861where uvc-gadget is this program: 862 http://git.ideasonboard.org/uvc-gadget.git 863 864with these patches: 865 866 http://www.spinics.net/lists/linux-usb/msg99220.html 867 868host:: 869 870 luvcview -f yuv 871 87219. PRINTER function 873==================== 874 875The function is provided by usb_f_printer.ko module. 876 877Function-specific configfs interface 878------------------------------------ 879 880The function name to use when creating the function directory is "printer". 881The printer function provides these attributes in its function directory: 882 883 ========== =========================================== 884 pnp_string Data to be passed to the host in pnp string 885 q_len Number of requests per endpoint 886 ========== =========================================== 887 888Testing the PRINTER function 889---------------------------- 890 891The most basic testing: 892 893device: run the gadget:: 894 895 # ls -l /devices/virtual/usb_printer_gadget/ 896 897should show g_printer<number>. 898 899If udev is active, then /dev/g_printer<number> should appear automatically. 900 901host: 902 903If udev is active, then e.g. /dev/usb/lp0 should appear. 904 905host->device transmission: 906 907device:: 908 909 # cat /dev/g_printer<number> 910 911host:: 912 913 # cat > /dev/usb/lp0 914 915device->host transmission:: 916 917 # cat > /dev/g_printer<number> 918 919host:: 920 921 # cat /dev/usb/lp0 922 923More advanced testing can be done with the prn_example 924described in Documentation/usb/gadget_printer.rst. 925 926 92720. UAC1 function (virtual ALSA card, using u_audio API) 928======================================================== 929 930The function is provided by usb_f_uac1.ko module. 931It will create a virtual ALSA card and the audio streams are simply 932sinked to and sourced from it. 933 934Function-specific configfs interface 935------------------------------------ 936 937The function name to use when creating the function directory is "uac1". 938The uac1 function provides these attributes in its function directory: 939 940 ================ ==================================================== 941 c_chmask capture channel mask 942 c_srate list of capture sampling rates (comma-separated) 943 c_ssize capture sample size (bytes) 944 c_mute_present capture mute control enable 945 c_volume_present capture volume control enable 946 c_volume_min capture volume control min value (in 1/256 dB) 947 c_volume_max capture volume control max value (in 1/256 dB) 948 c_volume_res capture volume control resolution (in 1/256 dB) 949 p_chmask playback channel mask 950 p_srate list of playback sampling rates (comma-separated) 951 p_ssize playback sample size (bytes) 952 p_mute_present playback mute control enable 953 p_volume_present playback volume control enable 954 p_volume_min playback volume control min value (in 1/256 dB) 955 p_volume_max playback volume control max value (in 1/256 dB) 956 p_volume_res playback volume control resolution (in 1/256 dB) 957 req_number the number of pre-allocated requests for both capture 958 and playback 959 function_name name of the interface 960 ================ ==================================================== 961 962The attributes have sane default values. 963 964Testing the UAC1 function 965------------------------- 966 967device: run the gadget 968host: aplay -l # should list our USB Audio Gadget 969 970This function does not require real hardware support, it just 971sends a stream of audio data to/from the host. In order to 972actually hear something at the device side, a command similar 973to this must be used at the device side:: 974 975 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 976 977e.g.:: 978 979 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 980 aplay -D default:CARD=OdroidU3 981 982 98321. MIDI2 function 984================== 985 986The function is provided by usb_f_midi2.ko module. 987It will create a virtual ALSA card containing a UMP rawmidi device 988where the UMP packet is looped back. In addition, a legacy rawmidi 989device is created. The UMP rawmidi is bound with ALSA sequencer 990clients, too. 991 992Function-specific configfs interface 993------------------------------------ 994 995The function name to use when creating the function directory is "midi2". 996The midi2 function provides these attributes in its function directory 997as the card top-level information: 998 999 ============= ================================================= 1000 process_ump Bool flag to process UMP Stream messages (0 or 1) 1001 static_block Bool flag for static blocks (0 or 1) 1002 iface_name Optional interface name string 1003 ============= ================================================= 1004 1005The directory contains a subdirectory "ep.0", and this provides the 1006attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): 1007 1008 ============= ================================================= 1009 protocol_caps MIDI protocol capabilities; 1010 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols 1011 protocol Default MIDI protocol (either 1 or 2) 1012 ep_name UMP Endpoint name string 1013 product_id Product ID string 1014 manufacturer Manufacture ID number (24 bit) 1015 family Device family ID number (16 bit) 1016 model Device model ID number (16 bit) 1017 sw_revision Software revision (32 bit) 1018 ============= ================================================= 1019 1020Each Endpoint subdirectory contains a subdirectory "block.0", which 1021represents the Function Block for Block 0 information. 1022Its attributes are: 1023 1024 ================= =============================================== 1025 name Function Block name string 1026 direction Direction of this FB 1027 1: input, 2: output, or 3: bidirectional 1028 first_group The first UMP Group number (0-15) 1029 num_groups The number of groups in this FB (1-16) 1030 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) 1031 midi1_num_groups The number of groups for MIDI 1.0 (0-16) 1032 ui_hint UI-hint of this FB 1033 0: unknown, 1: receiver, 2: sender, 3: both 1034 midi_ci_verison Supported MIDI-CI version number (8 bit) 1035 is_midi1 Legacy MIDI 1.0 device (0-2) 1036 0: MIDI 2.0 device, 1037 1: MIDI 1.0 without restriction, or 1038 2: MIDI 1.0 with low speed 1039 sysex8_streams Max number of SysEx8 streams (8 bit) 1040 active Bool flag for FB activity (0 or 1) 1041 ================= =============================================== 1042 1043If multiple Function Blocks are required, you can add more Function 1044Blocks by creating subdirectories "block.<num>" with the corresponding 1045Function Block number (1, 2, ....). The FB subdirectories can be 1046dynamically removed, too. Note that the Function Block numbers must be 1047continuous. 1048 1049Similarly, if you multiple UMP Endpoints are required, you can add 1050more Endpoints by creating subdirectories "ep.<num>". The number must 1051be continuous. 1052 1053For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 1054to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. 1055 1056Testing the MIDI2 function 1057-------------------------- 1058 1059On the device: run the gadget, and running:: 1060 1061 $ cat /proc/asound/cards 1062 1063will show a new sound card containing a MIDI2 device. 1064 1065OTOH, on the host:: 1066 1067 $ cat /proc/asound/cards 1068 1069will show a new sound card containing either MIDI1 or MIDI2 device, 1070depending on the USB audio driver configuration. 1071 1072On both, when ALSA sequencer is enabled on the host, you can find the 1073UMP MIDI client such as "MIDI 2.0 Gadget". 1074 1075As the driver simply loops back the data, there is no need for a real 1076device just for testing. 1077 1078For testing a MIDI input from the gadget to the host (e.g. emulating a 1079MIDI keyboard), you can send a MIDI stream like the following. 1080 1081On the gadget:: 1082 1083 $ aconnect -o 1084 .... 1085 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 1086 0 'MIDI 2.0 ' 1087 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1088 $ aplaymidi -p 20:1 to_host.mid 1089 1090On the host:: 1091 1092 $ aconnect -i 1093 .... 1094 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 1095 0 'MIDI 2.0 ' 1096 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1097 $ arecordmidi -p 24:1 from_gadget.mid 1098 1099If you have a UMP-capable application, you can use the UMP port to 1100send/receive the raw UMP packets, too. For example, aseqdump program 1101with UMP support can receive from UMP port. On the host:: 1102 1103 $ aseqdump -u 2 -p 24:1 1104 Waiting for data. Press Ctrl+C to end. 1105 Source Group Event Ch Data 1106 24:1 Group 0, Program change 0, program 0, Bank select 0:0 1107 24:1 Group 0, Channel pressure 0, value 0x80000000 1108 1109For testing a MIDI output to the gadget to the host (e.g. emulating a 1110MIDI synth), it'll be just other way round. 1111 1112On the gadget:: 1113 1114 $ arecordmidi -p 20:1 from_host.mid 1115 1116On the host:: 1117 1118 $ aplaymidi -p 24:1 to_gadget.mid 1119 1120The access to MIDI 1.0 on altset 0 on the host is supported, and it's 1121translated from/to UMP packets on the gadget. It's bound to only 1122Function Block 0. 1123 1124The current operation mode can be observed in ALSA control element 1125"Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: 1126 1127 $ amixer -c1 contents 1128 numid=1,iface=RAWMIDI,name='Operation Mode' 1129 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 1130 : values=2 1131 1132where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). 1133The example above shows it's running in 2, i.e. MIDI 2.0. 1134