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