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