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