1 ============== 2 Gadget Testing 3 ============== 4 5 This file summarizes information on basic testing of USB functions 6 provided 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 33 1. ACM function 34 =============== 35 36 The function is provided by usb_f_acm.ko module. 37 38 Function-specific configfs interface 39 ------------------------------------ 40 41 The function name to use when creating the function directory is "acm". 42 The ACM function provides just one attribute in its function directory: 43 44 port_num 45 46 The attribute is read-only. 47 48 There can be at most 4 ACM/generic serial/OBEX ports in the system. 49 50 51 Testing the ACM function 52 ------------------------ 53 54 On the host:: 55 56 cat > /dev/ttyACM<X> 57 58 On the device:: 59 60 cat /dev/ttyGS<Y> 61 62 then the other way round 63 64 On the device:: 65 66 cat > /dev/ttyGS<Y> 67 68 On the host:: 69 70 cat /dev/ttyACM<X> 71 72 2. ECM function 73 =============== 74 75 The function is provided by usb_f_ecm.ko module. 76 77 Function-specific configfs interface 78 ------------------------------------ 79 80 The function name to use when creating the function directory is "ecm". 81 The 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 93 and after creating the functions/ecm.<instance name> they contain default 94 values: qmult is 5, dev_addr and host_addr are randomly selected. 95 The ifname can be written to if the function is not bound. A write must be an 96 interface pattern such as "usb%d", which will cause the net core to choose the 97 next free usbX interface. By default, it is set to "usb%d". 98 99 Testing the ECM function 100 ------------------------ 101 102 Configure IP addresses of the device and the host. Then: 103 104 On the device:: 105 106 ping <host's IP> 107 108 On the host:: 109 110 ping <device's IP> 111 112 3. ECM subset function 113 ====================== 114 115 The function is provided by usb_f_ecm_subset.ko module. 116 117 Function-specific configfs interface 118 ------------------------------------ 119 120 The function name to use when creating the function directory is "geth". 121 The 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 133 and after creating the functions/ecm.<instance name> they contain default 134 values: qmult is 5, dev_addr and host_addr are randomly selected. 135 The ifname can be written to if the function is not bound. A write must be an 136 interface pattern such as "usb%d", which will cause the net core to choose the 137 next free usbX interface. By default, it is set to "usb%d". 138 139 Testing the ECM subset function 140 ------------------------------- 141 142 Configure IP addresses of the device and the host. Then: 143 144 On the device:: 145 146 ping <host's IP> 147 148 On the host:: 149 150 ping <device's IP> 151 152 4. EEM function 153 =============== 154 155 The function is provided by usb_f_eem.ko module. 156 157 Function-specific configfs interface 158 ------------------------------------ 159 160 The function name to use when creating the function directory is "eem". 161 The 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 173 and after creating the functions/eem.<instance name> they contain default 174 values: qmult is 5, dev_addr and host_addr are randomly selected. 175 The ifname can be written to if the function is not bound. A write must be an 176 interface pattern such as "usb%d", which will cause the net core to choose the 177 next free usbX interface. By default, it is set to "usb%d". 178 179 Testing the EEM function 180 ------------------------ 181 182 Configure IP addresses of the device and the host. Then: 183 184 On the device:: 185 186 ping <host's IP> 187 188 On the host:: 189 190 ping <device's IP> 191 192 5. FFS function 193 =============== 194 195 The function is provided by usb_f_fs.ko module. 196 197 Function-specific configfs interface 198 ------------------------------------ 199 200 The function name to use when creating the function directory is "ffs". 201 The function directory is intentionally empty and not modifiable. 202 203 After creating the directory there is a new instance (a "device") of FunctionFS 204 available in the system. Once a "device" is available, the user should follow 205 the standard procedure for using FunctionFS (mount it, run the userspace 206 process which implements the function proper). The gadget should be enabled 207 by writing a suitable string to usb_gadget/<gadget>/UDC. 208 209 The FFS function provides just one attribute in its function directory: 210 211 ready 212 213 The attribute is read-only and signals if the function is ready (1) to be 214 used, E.G. if userspace has written descriptors and strings to ep0, so 215 the gadget can be enabled. 216 217 Testing the FFS function 218 ------------------------ 219 220 On the device: start the function's userspace daemon, enable the gadget 221 222 On the host: use the USB function provided by the device 223 224 6. HID function 225 =============== 226 227 The function is provided by usb_f_hid.ko module. 228 229 Function-specific configfs interface 230 ------------------------------------ 231 232 The function name to use when creating the function directory is "hid". 233 The 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 243 For a keyboard the protocol and the subclass are 1, the report_length is 8, 244 while 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 253 Such a sequence of bytes can be stored to the attribute with echo:: 254 255 $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... 256 257 Testing the HID function 258 ------------------------ 259 260 Device: 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 270 Host: 271 272 - observe the keystrokes from the gadget 273 274 7. LOOPBACK function 275 ==================== 276 277 The function is provided by usb_f_ss_lb.ko module. 278 279 Function-specific configfs interface 280 ------------------------------------ 281 282 The function name to use when creating the function directory is "Loopback". 283 The LOOPBACK function provides these attributes in its function directory: 284 285 =============== ======================= 286 qlen depth of loopback queue 287 bulk_buflen buffer length 288 =============== ======================= 289 290 Testing the LOOPBACK function 291 ----------------------------- 292 293 device: run the gadget 294 295 host: test-usb (tools/usb/testusb.c) 296 297 8. MASS STORAGE function 298 ======================== 299 300 The function is provided by usb_f_mass_storage.ko module. 301 302 Function-specific configfs interface 303 ------------------------------------ 304 305 The function name to use when creating the function directory is "mass_storage". 306 The MASS STORAGE function provides these attributes in its directory: 307 files: 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 318 and a default lun.0 directory corresponding to SCSI LUN #0. 319 320 A new lun can be added with mkdir:: 321 322 $ mkdir functions/mass_storage.0/partition.5 323 324 Lun numbering does not have to be continuous, except for lun #0 which is 325 created by default. A maximum of 8 luns can be specified and they all must be 326 named following the <name>.<number> scheme. The numbers can be 0..8. 327 Probably a good convention is to name the luns "lun.<number>", 328 although it is not mandatory. 329 330 In 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 353 Testing the MASS STORAGE function 354 --------------------------------- 355 356 device: connect the gadget, enable it 357 host: dmesg, see the USB drives appear (if system configured to automatically 358 mount) 359 360 9. MIDI function 361 ================ 362 363 The function is provided by usb_f_midi.ko module. 364 365 Function-specific configfs interface 366 ------------------------------------ 367 368 The function name to use when creating the function directory is "midi". 369 The 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 380 Testing the MIDI function 381 ------------------------- 382 383 There are two cases: playing a mid from the gadget to 384 the host and playing a mid from the host to the gadget. 385 386 1) Playing a mid from the gadget to the host: 387 388 host:: 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 396 gadget:: 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 404 2) Playing a mid from the host to the gadget 405 406 gadget:: 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 414 host:: 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 423 The from_gadget.mid should sound identical to the to_host.mid. 424 425 The from_host.id should sound identical to the to_gadget.mid. 426 427 MIDI 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 440 MIDI ports can be logically connected using the aconnect utility, e.g.:: 441 442 $ aconnect 24:0 128:0 # try it on the host 443 444 After the gadget's MIDI port is connected to timidity's MIDI port, 445 whatever is played at the gadget side with aplaymidi -l is audible 446 in host's speakers/headphones. 447 448 10. NCM function 449 ================ 450 451 The function is provided by usb_f_ncm.ko module. 452 453 Function-specific configfs interface 454 ------------------------------------ 455 456 The function name to use when creating the function directory is "ncm". 457 The 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 471 and after creating the functions/ncm.<instance name> they contain default 472 values: qmult is 5, dev_addr and host_addr are randomly selected. 473 The ifname can be written to if the function is not bound. A write must be an 474 interface pattern such as "usb%d", which will cause the net core to choose the 475 next free usbX interface. By default, it is set to "usb%d". 476 477 Testing the NCM function 478 ------------------------ 479 480 Configure IP addresses of the device and the host. Then: 481 482 On the device:: 483 484 ping <host's IP> 485 486 On the host:: 487 488 ping <device's IP> 489 490 11. OBEX function 491 ================= 492 493 The function is provided by usb_f_obex.ko module. 494 495 Function-specific configfs interface 496 ------------------------------------ 497 498 The function name to use when creating the function directory is "obex". 499 The OBEX function provides just one attribute in its function directory: 500 501 port_num 502 503 The attribute is read-only. 504 505 There can be at most 4 ACM/generic serial/OBEX ports in the system. 506 507 Testing the OBEX function 508 ------------------------- 509 510 On device:: 511 512 seriald -f /dev/ttyGS<Y> -s 1024 513 514 On host:: 515 516 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ 517 -t<out endpoint addr> -r<in endpoint addr> 518 519 where seriald and serialc are Felipe's utilities found here: 520 521 https://github.com/felipebalbi/usb-tools.git master 522 523 12. PHONET function 524 =================== 525 526 The function is provided by usb_f_phonet.ko module. 527 528 Function-specific configfs interface 529 ------------------------------------ 530 531 The function name to use when creating the function directory is "phonet". 532 The 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 539 Testing the PHONET function 540 --------------------------- 541 542 It is not possible to test the SOCK_STREAM protocol without a specific piece 543 of hardware, so only SOCK_DGRAM has been tested. For the latter to work, 544 in the past I had to apply the patch mentioned here: 545 546 http://www.spinics.net/lists/linux-usb/msg85689.html 547 548 These tools are required: 549 550 git://git.gitorious.org/meego-cellular/phonet-utils.git 551 552 On the host:: 553 554 $ ./phonet -a 0x10 -i usbpn0 555 $ ./pnroute add 0x6c usbpn0 556 $./pnroute add 0x10 usbpn0 557 $ ifconfig usbpn0 up 558 559 On the device:: 560 561 $ ./phonet -a 0x6c -i upnlink0 562 $ ./pnroute add 0x10 upnlink0 563 $ ifconfig upnlink0 up 564 565 Then a test program can be used:: 566 567 http://www.spinics.net/lists/linux-usb/msg85690.html 568 569 On the device:: 570 571 $ ./pnxmit -a 0x6c -r 572 573 On the host:: 574 575 $ ./pnxmit -a 0x10 -s 0x6c 576 577 As a result some data should be sent from host to device. 578 Then the other way round: 579 580 On the host:: 581 582 $ ./pnxmit -a 0x10 -r 583 584 On the device:: 585 586 $ ./pnxmit -a 0x6c -s 0x10 587 588 13. RNDIS function 589 ================== 590 591 The function is provided by usb_f_rndis.ko module. 592 593 Function-specific configfs interface 594 ------------------------------------ 595 596 The function name to use when creating the function directory is "rndis". 597 The 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 609 and after creating the functions/rndis.<instance name> they contain default 610 values: qmult is 5, dev_addr and host_addr are randomly selected. 611 The ifname can be written to if the function is not bound. A write must be an 612 interface pattern such as "usb%d", which will cause the net core to choose the 613 next free usbX interface. By default, it is set to "usb%d". 614 615 Testing the RNDIS function 616 -------------------------- 617 618 Configure IP addresses of the device and the host. Then: 619 620 On the device:: 621 622 ping <host's IP> 623 624 On the host:: 625 626 ping <device's IP> 627 628 14. SERIAL function 629 =================== 630 631 The function is provided by usb_f_gser.ko module. 632 633 Function-specific configfs interface 634 ------------------------------------ 635 636 The function name to use when creating the function directory is "gser". 637 The SERIAL function provides just one attribute in its function directory: 638 639 port_num 640 641 The attribute is read-only. 642 643 There can be at most 4 ACM/generic serial/OBEX ports in the system. 644 645 Testing the SERIAL function 646 --------------------------- 647 648 On host:: 649 650 insmod usbserial 651 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id 652 653 On host:: 654 655 cat > /dev/ttyUSB<X> 656 657 On target:: 658 659 cat /dev/ttyGS<Y> 660 661 then the other way round 662 663 On target:: 664 665 cat > /dev/ttyGS<Y> 666 667 On host:: 668 669 cat /dev/ttyUSB<X> 670 671 15. SOURCESINK function 672 ======================= 673 674 The function is provided by usb_f_ss_lb.ko module. 675 676 Function-specific configfs interface 677 ------------------------------------ 678 679 The function name to use when creating the function directory is "SourceSink". 680 The 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 693 Testing the SOURCESINK function 694 ------------------------------- 695 696 device: run the gadget 697 698 host: test-usb (tools/usb/testusb.c) 699 700 701 16. UAC1 function (legacy implementation) 702 ========================================= 703 704 The function is provided by usb_f_uac1_legacy.ko module. 705 706 Function-specific configfs interface 707 ------------------------------------ 708 709 The function name to use when creating the function directory 710 is "uac1_legacy". 711 The 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 722 The attributes have sane default values. 723 724 Testing the UAC1 function 725 ------------------------- 726 727 device: run the gadget 728 729 host:: 730 731 aplay -l # should list our USB Audio Gadget 732 733 17. UAC2 function 734 ================= 735 736 The function is provided by usb_f_uac2.ko module. 737 738 Function-specific configfs interface 739 ------------------------------------ 740 741 The function name to use when creating the function directory is "uac2". 742 The uac2 function provides these attributes in its function directory: 743 744 ================ ==================================================== 745 c_chmask capture channel mask 746 c_srate list of capture sampling rates (comma-separated) 747 c_ssize capture sample size (bytes) 748 c_sync capture synchronization type (async/adaptive) 749 c_mute_present capture mute control enable 750 c_volume_present capture volume control enable 751 c_volume_min capture volume control min value (in 1/256 dB) 752 c_volume_max capture volume control max value (in 1/256 dB) 753 c_volume_res capture volume control resolution (in 1/256 dB) 754 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto) 755 fb_max maximum extra bandwidth in async mode 756 p_chmask playback channel mask 757 p_srate list of playback sampling rates (comma-separated) 758 p_ssize playback sample size (bytes) 759 p_mute_present playback mute control enable 760 p_volume_present playback volume control enable 761 p_volume_min playback volume control min value (in 1/256 dB) 762 p_volume_max playback volume control max value (in 1/256 dB) 763 p_volume_res playback volume control resolution (in 1/256 dB) 764 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto) 765 req_number the number of pre-allocated request for both capture 766 and playback 767 function_name name of the interface 768 c_terminal_type code of the capture terminal type 769 p_terminal_type code of the playback terminal type 770 ================ ==================================================== 771 772 The attributes have sane default values. 773 774 Testing the UAC2 function 775 ------------------------- 776 777 device: run the gadget 778 host: aplay -l # should list our USB Audio Gadget 779 780 This function does not require real hardware support, it just 781 sends a stream of audio data to/from the host. In order to 782 actually hear something at the device side, a command similar 783 to this must be used at the device side:: 784 785 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 786 787 e.g.:: 788 789 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 790 aplay -D default:CARD=OdroidU3 791 792 18. UVC function 793 ================ 794 795 The function is provided by usb_f_uvc.ko module. 796 797 Function-specific configfs interface 798 ------------------------------------ 799 800 The function name to use when creating the function directory is "uvc". 801 The uvc function provides these attributes in its function directory: 802 803 =================== ================================================ 804 streaming_interval interval for polling endpoint for data transfers 805 streaming_maxburst bMaxBurst for super speed companion descriptor 806 streaming_maxpacket maximum packet size this endpoint is capable of 807 sending or receiving when this configuration is 808 selected 809 function_name name of the interface 810 =================== ================================================ 811 812 There are also "control" and "streaming" subdirectories, each of which contain 813 a number of their subdirectories. There are some sane defaults provided, but 814 the user must provide the following: 815 816 ================== ==================================================== 817 control header create in control/header, link from control/class/fs 818 and/or control/class/ss 819 streaming header create in streaming/header, link from 820 streaming/class/fs and/or streaming/class/hs and/or 821 streaming/class/ss 822 format description create in streaming/mjpeg and/or 823 streaming/uncompressed 824 frame description create in streaming/mjpeg/<format> and/or in 825 streaming/uncompressed/<format> 826 ================== ==================================================== 827 828 Each frame description contains frame interval specification, and each 829 such specification consists of a number of lines with an interval value 830 in each line. The rules stated above are best illustrated with an example:: 831 832 # mkdir functions/uvc.usb0/control/header/h 833 # cd functions/uvc.usb0/control/ 834 # ln -s header/h class/fs 835 # ln -s header/h class/ss 836 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 837 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 838 666666 839 1000000 840 5000000 841 EOF 842 # cd $GADGET_CONFIGFS_ROOT 843 # mkdir functions/uvc.usb0/streaming/header/h 844 # cd functions/uvc.usb0/streaming/header/h 845 # ln -s ../../uncompressed/u 846 # cd ../../class/fs 847 # ln -s ../../header/h 848 # cd ../../class/hs 849 # ln -s ../../header/h 850 # cd ../../class/ss 851 # ln -s ../../header/h 852 853 854 Testing the UVC function 855 ------------------------ 856 857 device: run the gadget, modprobe vivid:: 858 859 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 860 861 where uvc-gadget is this program: 862 http://git.ideasonboard.org/uvc-gadget.git 863 864 with these patches: 865 866 http://www.spinics.net/lists/linux-usb/msg99220.html 867 868 host:: 869 870 luvcview -f yuv 871 872 19. PRINTER function 873 ==================== 874 875 The function is provided by usb_f_printer.ko module. 876 877 Function-specific configfs interface 878 ------------------------------------ 879 880 The function name to use when creating the function directory is "printer". 881 The printer function provides these attributes in its function directory: 882 883 ========== =========================================== 884 pnp_string Data to be passed to the host in pnp string 885 q_len Number of requests per endpoint 886 ========== =========================================== 887 888 Testing the PRINTER function 889 ---------------------------- 890 891 The most basic testing: 892 893 device: run the gadget:: 894 895 # ls -l /devices/virtual/usb_printer_gadget/ 896 897 should show g_printer<number>. 898 899 If udev is active, then /dev/g_printer<number> should appear automatically. 900 901 host: 902 903 If udev is active, then e.g. /dev/usb/lp0 should appear. 904 905 host->device transmission: 906 907 device:: 908 909 # cat /dev/g_printer<number> 910 911 host:: 912 913 # cat > /dev/usb/lp0 914 915 device->host transmission:: 916 917 # cat > /dev/g_printer<number> 918 919 host:: 920 921 # cat /dev/usb/lp0 922 923 More advanced testing can be done with the prn_example 924 described in Documentation/usb/gadget_printer.rst. 925 926 927 20. UAC1 function (virtual ALSA card, using u_audio API) 928 ======================================================== 929 930 The function is provided by usb_f_uac1.ko module. 931 It will create a virtual ALSA card and the audio streams are simply 932 sinked to and sourced from it. 933 934 Function-specific configfs interface 935 ------------------------------------ 936 937 The function name to use when creating the function directory is "uac1". 938 The uac1 function provides these attributes in its function directory: 939 940 ================ ==================================================== 941 c_chmask capture channel mask 942 c_srate list of capture sampling rates (comma-separated) 943 c_ssize capture sample size (bytes) 944 c_mute_present capture mute control enable 945 c_volume_present capture volume control enable 946 c_volume_min capture volume control min value (in 1/256 dB) 947 c_volume_max capture volume control max value (in 1/256 dB) 948 c_volume_res capture volume control resolution (in 1/256 dB) 949 p_chmask playback channel mask 950 p_srate list of playback sampling rates (comma-separated) 951 p_ssize playback sample size (bytes) 952 p_mute_present playback mute control enable 953 p_volume_present playback volume control enable 954 p_volume_min playback volume control min value (in 1/256 dB) 955 p_volume_max playback volume control max value (in 1/256 dB) 956 p_volume_res playback volume control resolution (in 1/256 dB) 957 req_number the number of pre-allocated requests for both capture 958 and playback 959 function_name name of the interface 960 ================ ==================================================== 961 962 The attributes have sane default values. 963 964 Testing the UAC1 function 965 ------------------------- 966 967 device: run the gadget 968 host: aplay -l # should list our USB Audio Gadget 969 970 This function does not require real hardware support, it just 971 sends a stream of audio data to/from the host. In order to 972 actually hear something at the device side, a command similar 973 to this must be used at the device side:: 974 975 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 976 977 e.g.:: 978 979 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 980 aplay -D default:CARD=OdroidU3 981 982 983 21. MIDI2 function 984 ================== 985 986 The function is provided by usb_f_midi2.ko module. 987 It will create a virtual ALSA card containing a UMP rawmidi device 988 where the UMP packet is looped back. In addition, a legacy rawmidi 989 device is created. The UMP rawmidi is bound with ALSA sequencer 990 clients, too. 991 992 Function-specific configfs interface 993 ------------------------------------ 994 995 The function name to use when creating the function directory is "midi2". 996 The midi2 function provides these attributes in its function directory 997 as the card top-level information: 998 999 ============= ================================================= 1000 process_ump Bool flag to process UMP Stream messages (0 or 1) 1001 static_block Bool flag for static blocks (0 or 1) 1002 iface_name Optional interface name string 1003 ============= ================================================= 1004 1005 The directory contains a subdirectory "ep.0", and this provides the 1006 attributes for a UMP Endpoint (which is a pair of USB MIDI Endpoints): 1007 1008 ============= ================================================= 1009 protocol_caps MIDI protocol capabilities; 1010 1: MIDI 1.0, 2: MIDI 2.0, or 3: both protocols 1011 protocol Default MIDI protocol (either 1 or 2) 1012 ep_name UMP Endpoint name string 1013 product_id Product ID string 1014 manufacturer Manufacture ID number (24 bit) 1015 family Device family ID number (16 bit) 1016 model Device model ID number (16 bit) 1017 sw_revision Software revision (32 bit) 1018 ============= ================================================= 1019 1020 Each Endpoint subdirectory contains a subdirectory "block.0", which 1021 represents the Function Block for Block 0 information. 1022 Its attributes are: 1023 1024 ================= =============================================== 1025 name Function Block name string 1026 direction Direction of this FB 1027 1: input, 2: output, or 3: bidirectional 1028 first_group The first UMP Group number (0-15) 1029 num_groups The number of groups in this FB (1-16) 1030 midi1_first_group The first UMP Group number for MIDI 1.0 (0-15) 1031 midi1_num_groups The number of groups for MIDI 1.0 (0-16) 1032 ui_hint UI-hint of this FB 1033 0: unknown, 1: receiver, 2: sender, 3: both 1034 midi_ci_verison Supported MIDI-CI version number (8 bit) 1035 is_midi1 Legacy MIDI 1.0 device (0-2) 1036 0: MIDI 2.0 device, 1037 1: MIDI 1.0 without restriction, or 1038 2: MIDI 1.0 with low speed 1039 sysex8_streams Max number of SysEx8 streams (8 bit) 1040 active Bool flag for FB activity (0 or 1) 1041 ================= =============================================== 1042 1043 If multiple Function Blocks are required, you can add more Function 1044 Blocks by creating subdirectories "block.<num>" with the corresponding 1045 Function Block number (1, 2, ....). The FB subdirectories can be 1046 dynamically removed, too. Note that the Function Block numbers must be 1047 continuous. 1048 1049 Similarly, if you multiple UMP Endpoints are required, you can add 1050 more Endpoints by creating subdirectories "ep.<num>". The number must 1051 be continuous. 1052 1053 For emulating the old MIDI 2.0 device without UMP v1.1 support, pass 0 1054 to `process_ump` flag. Then the whole UMP v1.1 requests are ignored. 1055 1056 Testing the MIDI2 function 1057 -------------------------- 1058 1059 On the device: run the gadget, and running:: 1060 1061 $ cat /proc/asound/cards 1062 1063 will show a new sound card containing a MIDI2 device. 1064 1065 OTOH, on the host:: 1066 1067 $ cat /proc/asound/cards 1068 1069 will show a new sound card containing either MIDI1 or MIDI2 device, 1070 depending on the USB audio driver configuration. 1071 1072 On both, when ALSA sequencer is enabled on the host, you can find the 1073 UMP MIDI client such as "MIDI 2.0 Gadget". 1074 1075 As the driver simply loops back the data, there is no need for a real 1076 device just for testing. 1077 1078 For testing a MIDI input from the gadget to the host (e.g. emulating a 1079 MIDI keyboard), you can send a MIDI stream like the following. 1080 1081 On the gadget:: 1082 1083 $ aconnect -o 1084 .... 1085 client 20: 'MIDI 2.0 Gadget' [type=kernel,card=1] 1086 0 'MIDI 2.0 ' 1087 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1088 $ aplaymidi -p 20:1 to_host.mid 1089 1090 On the host:: 1091 1092 $ aconnect -i 1093 .... 1094 client 24: 'MIDI 2.0 Gadget' [type=kernel,card=2] 1095 0 'MIDI 2.0 ' 1096 1 'Group 1 (MIDI 2.0 Gadget I/O)' 1097 $ arecordmidi -p 24:1 from_gadget.mid 1098 1099 If you have a UMP-capable application, you can use the UMP port to 1100 send/receive the raw UMP packets, too. For example, aseqdump program 1101 with UMP support can receive from UMP port. On the host:: 1102 1103 $ aseqdump -u 2 -p 24:1 1104 Waiting for data. Press Ctrl+C to end. 1105 Source Group Event Ch Data 1106 24:1 Group 0, Program change 0, program 0, Bank select 0:0 1107 24:1 Group 0, Channel pressure 0, value 0x80000000 1108 1109 For testing a MIDI output to the gadget to the host (e.g. emulating a 1110 MIDI synth), it'll be just other way round. 1111 1112 On the gadget:: 1113 1114 $ arecordmidi -p 20:1 from_host.mid 1115 1116 On the host:: 1117 1118 $ aplaymidi -p 24:1 to_gadget.mid 1119 1120 The access to MIDI 1.0 on altset 0 on the host is supported, and it's 1121 translated from/to UMP packets on the gadget. It's bound to only 1122 Function Block 0. 1123 1124 The current operation mode can be observed in ALSA control element 1125 "Operation Mode" for SND_CTL_IFACE_RAWMIDI. For example:: 1126 1127 $ amixer -c1 contents 1128 numid=1,iface=RAWMIDI,name='Operation Mode' 1129 ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 1130 : values=2 1131 1132 where 0 = unused, 1 = MIDI 1.0 (altset 0), 2 = MIDI 2.0 (altset 1). 1133 The example above shows it's running in 2, i.e. MIDI 2.0.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.