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://github.com/felipebalbi/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 bulk_qlen - depth of queue for bulk 583 iso_qlen - depth of queue for iso 584 585Testing the SOURCESINK function 586------------------------------- 587 588device: run the gadget 589host: test-usb (tools/usb/testusb.c) 590 591 59216. UAC1 function 593================= 594 595The function is provided by usb_f_uac1.ko module. 596 597Function-specific configfs interface 598------------------------------------ 599 600The function name to use when creating the function directory is "uac1". 601The uac1 function provides these attributes in its function directory: 602 603 audio_buf_size - audio buffer size 604 fn_cap - capture pcm device file name 605 fn_cntl - control device file name 606 fn_play - playback pcm device file name 607 req_buf_size - ISO OUT endpoint request buffer size 608 req_count - ISO OUT endpoint request count 609 610The attributes have sane default values. 611 612Testing the UAC1 function 613------------------------- 614 615device: run the gadget 616host: aplay -l # should list our USB Audio Gadget 617 61817. UAC2 function 619================= 620 621The function is provided by usb_f_uac2.ko module. 622 623Function-specific configfs interface 624------------------------------------ 625 626The function name to use when creating the function directory is "uac2". 627The uac2 function provides these attributes in its function directory: 628 629 c_chmask - capture channel mask 630 c_srate - capture sampling rate 631 c_ssize - capture sample size (bytes) 632 p_chmask - playback channel mask 633 p_srate - playback sampling rate 634 p_ssize - playback sample size (bytes) 635 636The attributes have sane default values. 637 638Testing the UAC2 function 639------------------------- 640 641device: run the gadget 642host: aplay -l # should list our USB Audio Gadget 643 644This function does not require real hardware support, it just 645sends a stream of audio data to/from the host. In order to 646actually hear something at the device side, a command similar 647to this must be used at the device side: 648 649$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & 650 651e.g.: 652 653$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ 654aplay -D default:CARD=OdroidU3 655 65618. UVC function 657================ 658 659The function is provided by usb_f_uvc.ko module. 660 661Function-specific configfs interface 662------------------------------------ 663 664The function name to use when creating the function directory is "uvc". 665The uvc function provides these attributes in its function directory: 666 667 streaming_interval - interval for polling endpoint for data transfers 668 streaming_maxburst - bMaxBurst for super speed companion descriptor 669 streaming_maxpacket - maximum packet size this endpoint is capable of 670 sending or receiving when this configuration is 671 selected 672 673There are also "control" and "streaming" subdirectories, each of which contain 674a number of their subdirectories. There are some sane defaults provided, but 675the user must provide the following: 676 677 control header - create in control/header, link from control/class/fs 678 and/or control/class/ss 679 streaming header - create in streaming/header, link from 680 streaming/class/fs and/or streaming/class/hs and/or 681 streaming/class/ss 682 format description - create in streaming/mjpeg and/or 683 streaming/uncompressed 684 frame description - create in streaming/mjpeg/<format> and/or in 685 streaming/uncompressed/<format> 686 687Each frame description contains frame interval specification, and each 688such specification consists of a number of lines with an inverval value 689in each line. The rules stated above are best illustrated with an example: 690 691# mkdir functions/uvc.usb0/control/header/h 692# cd functions/uvc.usb0/control/header/h 693# ln -s header/h class/fs 694# ln -s header/h class/ss 695# mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p 696# cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval 697666666 6981000000 6995000000 700EOF 701# cd $GADGET_CONFIGFS_ROOT 702# mkdir functions/uvc.usb0/streaming/header/h 703# cd functions/uvc.usb0/streaming/header/h 704# ln -s ../../uncompressed/u 705# cd ../../class/fs 706# ln -s ../../header/h 707# cd ../../class/hs 708# ln -s ../../header/h 709# cd ../../class/ss 710# ln -s ../../header/h 711 712 713Testing the UVC function 714------------------------ 715 716device: run the gadget, modprobe vivid 717 718# uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> 719 720where uvc-gadget is this program: 721http://git.ideasonboard.org/uvc-gadget.git 722 723with these patches: 724http://www.spinics.net/lists/linux-usb/msg99220.html 725 726host: luvcview -f yuv 727 72819. PRINTER function 729==================== 730 731The function is provided by usb_f_printer.ko module. 732 733Function-specific configfs interface 734------------------------------------ 735 736The function name to use when creating the function directory is "printer". 737The printer function provides these attributes in its function directory: 738 739 pnp_string - Data to be passed to the host in pnp string 740 q_len - Number of requests per endpoint 741 742Testing the PRINTER function 743---------------------------- 744 745The most basic testing: 746 747device: run the gadget 748# ls -l /devices/virtual/usb_printer_gadget/ 749 750should show g_printer<number>. 751 752If udev is active, then /dev/g_printer<number> should appear automatically. 753 754host: 755 756If udev is active, then e.g. /dev/usb/lp0 should appear. 757 758host->device transmission: 759 760device: 761# cat /dev/g_printer<number> 762host: 763# cat > /dev/usb/lp0 764 765device->host transmission: 766 767# cat > /dev/g_printer<number> 768host: 769# cat /dev/usb/lp0 770 771More advanced testing can be done with the prn_example 772described in Documentation/usb/gadget-printer.txt. 773