1This file summarizes information on basic testing of USB functions 2provided by gadgets. 3 41. ACM function 52. ECM function 63. ECM subset function 74. EEM function 85. FFS function 96. HID function 107. LOOPBACK function 118. MASS STORAGE function 129. MIDI function 1310. NCM function 1411. OBEX function 1512. PHONET function 1613. RNDIS function 1714. SERIAL function 1815. SOURCESINK function 1916. UAC1 function (legacy implementation) 2017. UAC2 function 2118. UVC function 2219. PRINTER function 2320. UAC1 function (new API) 24 25 261. ACM function 27=============== 28 29The function is provided by usb_f_acm.ko module. 30 31Function-specific configfs interface 32------------------------------------ 33 34The function name to use when creating the function directory is "acm". 35The ACM function provides just one attribute in its function directory: 36 37 port_num 38 39The attribute is read-only. 40 41There can be at most 4 ACM/generic serial/OBEX ports in the system. 42 43 44Testing the ACM function 45------------------------ 46 47On the host: cat > /dev/ttyACM<X> 48On the device : cat /dev/ttyGS<Y> 49 50then the other way round 51 52On the device: cat > /dev/ttyGS<Y> 53On the host: cat /dev/ttyACM<X> 54 552. ECM function 56=============== 57 58The function is provided by usb_f_ecm.ko module. 59 60Function-specific configfs interface 61------------------------------------ 62 63The function name to use when creating the function directory is "ecm". 64The ECM function provides these attributes in its function directory: 65 66 ifname - network device interface name associated with this 67 function instance 68 qmult - queue length multiplier for high and super speed 69 host_addr - MAC address of host's end of this 70 Ethernet over USB link 71 dev_addr - MAC address of device's end of this 72 Ethernet over USB link 73 74and after creating the functions/ecm.<instance name> they contain default 75values: qmult is 5, dev_addr and host_addr are randomly selected. 76Except for ifname they can be written to until the function is linked to a 77configuration. The ifname is read-only and contains the name of the interface 78which was assigned by the net core, e. g. usb0. 79 80Testing the ECM function 81------------------------ 82 83Configure IP addresses of the device and the host. Then: 84 85On the device: ping <host's IP> 86On the host: ping <device's IP> 87 883. ECM subset function 89====================== 90 91The function is provided by usb_f_ecm_subset.ko module. 92 93Function-specific configfs interface 94------------------------------------ 95 96The function name to use when creating the function directory is "geth". 97The ECM subset function provides these attributes in its function directory: 98 99 ifname - network device interface name associated with this 100 function instance 101 qmult - queue length multiplier for high and super speed 102 host_addr - MAC address of host's end of this 103 Ethernet over USB link 104 dev_addr - MAC address of device's end of this 105 Ethernet over USB link 106 107and after creating the functions/ecm.<instance name> they contain default 108values: qmult is 5, dev_addr and host_addr are randomly selected. 109Except for ifname they can be written to until the function is linked to a 110configuration. The ifname is read-only and contains the name of the interface 111which was assigned by the net core, e. g. usb0. 112 113Testing the ECM subset function 114------------------------------- 115 116Configure IP addresses of the device and the host. Then: 117 118On the device: ping <host's IP> 119On the host: ping <device's IP> 120 1214. EEM function 122=============== 123 124The function is provided by usb_f_eem.ko module. 125 126Function-specific configfs interface 127------------------------------------ 128 129The function name to use when creating the function directory is "eem". 130The EEM function provides these attributes in its function directory: 131 132 ifname - network device interface name associated with this 133 function instance 134 qmult - queue length multiplier for high and super speed 135 host_addr - MAC address of host's end of this 136 Ethernet over USB link 137 dev_addr - MAC address of device's end of this 138 Ethernet over USB link 139 140and after creating the functions/eem.<instance name> they contain default 141values: qmult is 5, dev_addr and host_addr are randomly selected. 142Except for ifname they can be written to until the function is linked to a 143configuration. The ifname is read-only and contains the name of the interface 144which was assigned by the net core, e. g. usb0. 145 146Testing the EEM function 147------------------------ 148 149Configure IP addresses of the device and the host. Then: 150 151On the device: ping <host's IP> 152On the host: ping <device's IP> 153 1545. FFS function 155=============== 156 157The function is provided by usb_f_fs.ko module. 158 159Function-specific configfs interface 160------------------------------------ 161 162The function name to use when creating the function directory is "ffs". 163The function directory is intentionally empty and not modifiable. 164 165After creating the directory there is a new instance (a "device") of FunctionFS 166available in the system. Once a "device" is available, the user should follow 167the standard procedure for using FunctionFS (mount it, run the userspace 168process which implements the function proper). The gadget should be enabled 169by writing a suitable string to usb_gadget/<gadget>/UDC. 170 171Testing the FFS function 172------------------------ 173 174On the device: start the function's userspace daemon, enable the gadget 175On the host: use the USB function provided by the device 176 1776. HID function 178=============== 179 180The function is provided by usb_f_hid.ko module. 181 182Function-specific configfs interface 183------------------------------------ 184 185The function name to use when creating the function directory is "hid". 186The HID function provides these attributes in its function directory: 187 188 protocol - HID protocol to use 189 report_desc - data to be used in HID reports, except data 190 passed with /dev/hidg<X> 191 report_length - HID report length 192 subclass - HID subclass to use 193 194For a keyboard the protocol and the subclass are 1, the report_length is 8, 195while the report_desc is: 196 197$ hd my_report_desc 19800000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| 19900000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| 20000000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| 20100000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| 2020000003f 203 204Such a sequence of bytes can be stored to the attribute with echo: 205 206$ echo -ne \\x05\\x01\\x09\\x06\\xa1..... 207 208Testing the HID function 209------------------------ 210 211Device: 212- create the gadget 213- connect the gadget to a host, preferably not the one used 214to control the gadget 215- run a program which writes to /dev/hidg<N>, e.g. 216a userspace program found in Documentation/usb/gadget_hid.txt: 217 218$ ./hid_gadget_test /dev/hidg0 keyboard 219 220Host: 221- observe the keystrokes from the gadget 222 2237. LOOPBACK function 224==================== 225 226The function is provided by usb_f_ss_lb.ko module. 227 228Function-specific configfs interface 229------------------------------------ 230 231The function name to use when creating the function directory is "Loopback". 232The LOOPBACK function provides these attributes in its function directory: 233 234 qlen - depth of loopback queue 235 bulk_buflen - buffer length 236 237Testing the LOOPBACK function 238----------------------------- 239 240device: run the gadget 241host: test-usb (tools/usb/testusb.c) 242 2438. MASS STORAGE function 244======================== 245 246The function is provided by usb_f_mass_storage.ko module. 247 248Function-specific configfs interface 249------------------------------------ 250 251The function name to use when creating the function directory is "mass_storage". 252The MASS STORAGE function provides these attributes in its directory: 253files: 254 255 stall - Set to permit function to halt bulk endpoints. 256 Disabled on some USB devices known not to work 257 correctly. You should set it to true. 258 num_buffers - Number of pipeline buffers. Valid numbers 259 are 2..4. Available only if 260 CONFIG_USB_GADGET_DEBUG_FILES is set. 261 262and a default lun.0 directory corresponding to SCSI LUN #0. 263 264A new lun can be added with mkdir: 265 266$ mkdir functions/mass_storage.0/partition.5 267 268Lun numbering does not have to be continuous, except for lun #0 which is 269created by default. A maximum of 8 luns can be specified and they all must be 270named following the <name>.<number> scheme. The numbers can be 0..8. 271Probably a good convention is to name the luns "lun.<number>", 272although it is not mandatory. 273 274In each lun directory there are the following attribute files: 275 276 file - The path to the backing file for the LUN. 277 Required if LUN is not marked as removable. 278 ro - Flag specifying access to the LUN shall be 279 read-only. This is implied if CD-ROM emulation 280 is enabled as well as when it was impossible 281 to open "filename" in R/W mode. 282 removable - Flag specifying that LUN shall be indicated as 283 being removable. 284 cdrom - Flag specifying that LUN shall be reported as 285 being a CD-ROM. 286 nofua - Flag specifying that FUA flag 287 in SCSI WRITE(10,12) 288 289Testing the MASS STORAGE function 290--------------------------------- 291 292device: connect the gadget, enable it 293host: dmesg, see the USB drives appear (if system configured to automatically 294mount) 295 2969. MIDI function 297================ 298 299The function is provided by usb_f_midi.ko module. 300 301Function-specific configfs interface 302------------------------------------ 303 304The function name to use when creating the function directory is "midi". 305The MIDI function provides these attributes in its function directory: 306 307 buflen - MIDI buffer length 308 id - ID string for the USB MIDI adapter 309 in_ports - number of MIDI input ports 310 index - index value for the USB MIDI adapter 311 out_ports - number of MIDI output ports 312 qlen - USB read request queue length 313 314Testing the MIDI function 315------------------------- 316 317There are two cases: playing a mid from the gadget to 318the host and playing a mid from the host to the gadget. 319 3201) Playing a mid from the gadget to the host 321host) 322 323$ arecordmidi -l 324 Port Client name Port name 325 14:0 Midi Through Midi Through Port-0 326 24:0 MIDI Gadget MIDI Gadget MIDI 1 327$ arecordmidi -p 24:0 from_gadget.mid 328 329gadget) 330 331$ aplaymidi -l 332 Port Client name Port name 333 20:0 f_midi f_midi 334 335$ aplaymidi -p 20:0 to_host.mid 336 3372) Playing a mid from the host to the gadget 338gadget) 339 340$ arecordmidi -l 341 Port Client name Port name 342 20:0 f_midi f_midi 343 344$ arecordmidi -p 20:0 from_host.mid 345 346host) 347 348$ aplaymidi -l 349 Port Client name Port name 350 14:0 Midi Through Midi Through Port-0 351 24:0 MIDI Gadget MIDI Gadget MIDI 1 352 353$ aplaymidi -p24:0 to_gadget.mid 354 355The from_gadget.mid should sound identical to the to_host.mid. 356The from_host.id should sound identical to the to_gadget.mid. 357 358MIDI files can be played to speakers/headphones with e.g. timidity installed 359 360$ aplaymidi -l 361 Port Client name Port name 362 14:0 Midi Through Midi Through Port-0 363 24:0 MIDI Gadget MIDI Gadget MIDI 1 364128:0 TiMidity TiMidity port 0 365128:1 TiMidity TiMidity port 1 366128:2 TiMidity TiMidity port 2 367128:3 TiMidity TiMidity port 3 368 369$ aplaymidi -p 128:0 file.mid 370 371MIDI ports can be logically connected using the aconnect utility, e.g.: 372 373$ aconnect 24:0 128:0 # try it on the host 374 375After the gadget's MIDI port is connected to timidity's MIDI port, 376whatever is played at the gadget side with aplaymidi -l is audible 377in host's speakers/headphones. 378 37910. NCM function 380================ 381 382The function is provided by usb_f_ncm.ko module. 383 384Function-specific configfs interface 385------------------------------------ 386 387The function name to use when creating the function directory is "ncm". 388The NCM function provides these attributes in its function directory: 389 390 ifname - network device interface name associated with this 391 function instance 392 qmult - queue length multiplier for high and super speed 393 host_addr - MAC address of host's end of this 394 Ethernet over USB link 395 dev_addr - MAC address of device's end of this 396 Ethernet over USB link 397 398and after creating the functions/ncm.<instance name> they contain default 399values: qmult is 5, dev_addr and host_addr are randomly selected. 400Except for ifname they can be written to until the function is linked to a 401configuration. The ifname is read-only and contains the name of the interface 402which was assigned by the net core, e. g. usb0. 403 404Testing the NCM function 405------------------------ 406 407Configure IP addresses of the device and the host. Then: 408 409On the device: ping <host's IP> 410On the host: ping <device's IP> 411 41211. OBEX function 413================= 414 415The function is provided by usb_f_obex.ko module. 416 417Function-specific configfs interface 418------------------------------------ 419 420The function name to use when creating the function directory is "obex". 421The OBEX function provides just one attribute in its function directory: 422 423 port_num 424 425The attribute is read-only. 426 427There can be at most 4 ACM/generic serial/OBEX ports in the system. 428 429Testing the OBEX function 430------------------------- 431 432On device: seriald -f /dev/ttyGS<Y> -s 1024 433On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ 434 -t<out endpoint addr> -r<in endpoint addr> 435 436where seriald and serialc are Felipe's utilities found here: 437 438https://github.com/felipebalbi/usb-tools.git master 439 44012. PHONET function 441=================== 442 443The function is provided by usb_f_phonet.ko module. 444 445Function-specific configfs interface 446------------------------------------ 447 448The function name to use when creating the function directory is "phonet". 449The PHONET function provides just one attribute in its function directory: 450 451 ifname - network device interface name associated with this 452 function instance 453 454Testing the PHONET function 455--------------------------- 456 457It is not possible to test the SOCK_STREAM protocol without a specific piece 458of hardware, so only SOCK_DGRAM has been tested. For the latter to work, 459in the past I had to apply the patch mentioned here: 460 461http://www.spinics.net/lists/linux-usb/msg85689.html 462 463These tools are required: 464 465git://git.gitorious.org/meego-cellular/phonet-utils.git 466 467On the host: 468 469$ ./phonet -a 0x10 -i usbpn0 470$ ./pnroute add 0x6c usbpn0 471$./pnroute add 0x10 usbpn0 472$ ifconfig usbpn0 up 473 474On the device: 475 476$ ./phonet -a 0x6c -i upnlink0 477$ ./pnroute add 0x10 upnlink0 478$ ifconfig upnlink0 up 479 480Then a test program can be used: 481 482http://www.spinics.net/lists/linux-usb/msg85690.html 483 484On the device: 485 486$ ./pnxmit -a 0x6c -r 487 488On the host: 489 490$ ./pnxmit -a 0x10 -s 0x6c 491 492As a result some data should be sent from host to device. 493Then the other way round: 494 495On the host: 496 497$ ./pnxmit -a 0x10 -r 498 499On the device: 500 501$ ./pnxmit -a 0x6c -s 0x10 502 50313. RNDIS function 504================== 505 506The function is provided by usb_f_rndis.ko module. 507 508Function-specific configfs interface 509------------------------------------ 510 511The function name to use when creating the function directory is "rndis". 512The RNDIS function provides these attributes in its function directory: 513 514 ifname - network device interface name associated with this 515 function instance 516 qmult - queue length multiplier for high and super speed 517 host_addr - MAC address of host's end of this 518 Ethernet over USB link 519 dev_addr - MAC address of device's end of this 520 Ethernet over USB link 521 522and after creating the functions/rndis.<instance name> they contain default 523values: qmult is 5, dev_addr and host_addr are randomly selected. 524Except for ifname they can be written to until the function is linked to a 525configuration. The ifname is read-only and contains the name of the interface 526which was assigned by the net core, e. g. usb0. 527 528Testing the RNDIS function 529-------------------------- 530 531Configure IP addresses of the device and the host. Then: 532 533On the device: ping <host's IP> 534On the host: ping <device's IP> 535 53614. SERIAL function 537=================== 538 539The function is provided by usb_f_gser.ko module. 540 541Function-specific configfs interface 542------------------------------------ 543 544The function name to use when creating the function directory is "gser". 545The SERIAL function provides just one attribute in its function directory: 546 547 port_num 548 549The attribute is read-only. 550 551There can be at most 4 ACM/generic serial/OBEX ports in the system. 552 553Testing the SERIAL function 554--------------------------- 555 556On host: insmod usbserial 557 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id 558On host: cat > /dev/ttyUSB<X> 559On target: cat /dev/ttyGS<Y> 560 561then the other way round 562 563On target: cat > /dev/ttyGS<Y> 564On host: cat /dev/ttyUSB<X> 565 56615. SOURCESINK function 567======================= 568 569The function is provided by usb_f_ss_lb.ko module. 570 571Function-specific configfs interface 572------------------------------------ 573 574The function name to use when creating the function directory is "SourceSink". 575The SOURCESINK function provides these attributes in its function directory: 576 577 pattern - 0 (all zeros), 1 (mod63), 2 (none) 578 isoc_interval - 1..16 579 isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss) 580 isoc_mult - 0..2 (hs/ss only) 581 isoc_maxburst - 0..15 (ss only) 582 bulk_buflen - buffer length 583 bulk_qlen - depth of queue for bulk 584 iso_qlen - depth of queue for iso 585 586Testing the SOURCESINK function 587------------------------------- 588 589device: run the gadget 590host: test-usb (tools/usb/testusb.c) 591 592 59316. UAC1 function (legacy implementation) 594================= 595 596The function is provided by usb_f_uac1_legacy.ko module. 597 598Function-specific configfs interface 599------------------------------------ 600 601The function name to use when creating the function directory 602is "uac1_legacy". 603The uac1 function provides these attributes in its function directory: 604 605 audio_buf_size - audio buffer size 606 fn_cap - capture pcm device file name 607 fn_cntl - control device file name 608 fn_play - playback pcm device file name 609 req_buf_size - ISO OUT endpoint request buffer size 610 req_count - ISO OUT endpoint request count 611 612The attributes have sane default values. 613 614Testing the UAC1 function 615------------------------- 616 617device: run the gadget 618host: aplay -l # should list our USB Audio Gadget 619 62017. UAC2 function 621================= 622 623The function is provided by usb_f_uac2.ko module. 624 625Function-specific configfs interface 626------------------------------------ 627 628The function name to use when creating the function directory is "uac2". 629The uac2 function provides these attributes in its function directory: 630 631 c_chmask - capture channel mask 632 c_srate - capture sampling rate 633 c_ssize - capture sample size (bytes) 634 p_chmask - playback channel mask 635 p_srate - playback sampling rate 636 p_ssize - playback sample size (bytes) 637 req_number - the number of pre-allocated request for both capture 638 and playback 639 640The attributes have sane default values. 641 642Testing the UAC2 function 643------------------------- 644 645device: run the gadget 646host: aplay -l # should list our USB Audio Gadget 647 648This function does not require real hardware support, it just 649sends a stream of audio data to/from the host. In order to 650actually hear something at the device side, a command similar 651to this must be used at the device side: 652 653$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 654 655e.g.: 656 657$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 658aplay -D default:CARD=OdroidU3 659 66018. UVC function 661================ 662 663The function is provided by usb_f_uvc.ko module. 664 665Function-specific configfs interface 666------------------------------------ 667 668The function name to use when creating the function directory is "uvc". 669The uvc function provides these attributes in its function directory: 670 671 streaming_interval - interval for polling endpoint for data transfers 672 streaming_maxburst - bMaxBurst for super speed companion descriptor 673 streaming_maxpacket - maximum packet size this endpoint is capable of 674 sending or receiving when this configuration is 675 selected 676 677There are also "control" and "streaming" subdirectories, each of which contain 678a number of their subdirectories. There are some sane defaults provided, but 679the user must provide the following: 680 681 control header - create in control/header, link from control/class/fs 682 and/or control/class/ss 683 streaming header - create in streaming/header, link from 684 streaming/class/fs and/or streaming/class/hs and/or 685 streaming/class/ss 686 format description - create in streaming/mjpeg and/or 687 streaming/uncompressed 688 frame description - create in streaming/mjpeg/<format> and/or in 689 streaming/uncompressed/<format> 690 691Each frame description contains frame interval specification, and each 692such specification consists of a number of lines with an inverval value 693in each line. The rules stated above are best illustrated with an example: 694 695# mkdir functions/uvc.usb0/control/header/h 696# cd functions/uvc.usb0/control/ 697# ln -s header/h class/fs 698# ln -s header/h class/ss 699# mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 700# cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 701666666 7021000000 7035000000 704EOF 705# cd $GADGET_CONFIGFS_ROOT 706# mkdir functions/uvc.usb0/streaming/header/h 707# cd functions/uvc.usb0/streaming/header/h 708# ln -s ../../uncompressed/u 709# cd ../../class/fs 710# ln -s ../../header/h 711# cd ../../class/hs 712# ln -s ../../header/h 713# cd ../../class/ss 714# ln -s ../../header/h 715 716 717Testing the UVC function 718------------------------ 719 720device: run the gadget, modprobe vivid 721 722# uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 723 724where uvc-gadget is this program: 725http://git.ideasonboard.org/uvc-gadget.git 726 727with these patches: 728http://www.spinics.net/lists/linux-usb/msg99220.html 729 730host: luvcview -f yuv 731 73219. PRINTER function 733==================== 734 735The function is provided by usb_f_printer.ko module. 736 737Function-specific configfs interface 738------------------------------------ 739 740The function name to use when creating the function directory is "printer". 741The printer function provides these attributes in its function directory: 742 743 pnp_string - Data to be passed to the host in pnp string 744 q_len - Number of requests per endpoint 745 746Testing the PRINTER function 747---------------------------- 748 749The most basic testing: 750 751device: run the gadget 752# ls -l /devices/virtual/usb_printer_gadget/ 753 754should show g_printer<number>. 755 756If udev is active, then /dev/g_printer<number> should appear automatically. 757 758host: 759 760If udev is active, then e.g. /dev/usb/lp0 should appear. 761 762host->device transmission: 763 764device: 765# cat /dev/g_printer<number> 766host: 767# cat > /dev/usb/lp0 768 769device->host transmission: 770 771# cat > /dev/g_printer<number> 772host: 773# cat /dev/usb/lp0 774 775More advanced testing can be done with the prn_example 776described in Documentation/usb/gadget_printer.txt. 777 778 77920. UAC1 function (virtual ALSA card, using u_audio API) 780================= 781 782The function is provided by usb_f_uac1.ko module. 783It will create a virtual ALSA card and the audio streams are simply 784sinked to and sourced from it. 785 786Function-specific configfs interface 787------------------------------------ 788 789The function name to use when creating the function directory is "uac1". 790The uac1 function provides these attributes in its function directory: 791 792 c_chmask - capture channel mask 793 c_srate - capture sampling rate 794 c_ssize - capture sample size (bytes) 795 p_chmask - playback channel mask 796 p_srate - playback sampling rate 797 p_ssize - playback sample size (bytes) 798 req_number - the number of pre-allocated request for both capture 799 and playback 800 801The attributes have sane default values. 802 803Testing the UAC1 function 804------------------------- 805 806device: run the gadget 807host: aplay -l # should list our USB Audio Gadget 808 809This function does not require real hardware support, it just 810sends a stream of audio data to/from the host. In order to 811actually hear something at the device side, a command similar 812to this must be used at the device side: 813 814$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 815 816e.g.: 817 818$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ 819aplay -D default:CARD=OdroidU3 820
