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