Documentation/usb/gadget-testing.txt

   1 This file summarizes information on basic testing of USB functions
   2 provided by gadgets.
   3
   4 1. ACM function
   5 2. ECM function
   6 3. ECM subset function
   7 4. EEM function
   8 5. FFS function
   9 6. HID function
  10 7. LOOPBACK function
  11 8. MASS STORAGE function
  12 9. MIDI function
  13 10. NCM function
  14 11. OBEX function
  15 12. PHONET function
  16 13. RNDIS function
  17 14. SERIAL function
  18 15. SOURCESINK function
  19 16. UAC1 function
  20 17. UAC2 function
  21 18. UVC function
  22
  23
  24 1. ACM function
  25 ===============
  26
  27 The function is provided by usb_f_acm.ko module.
  28
  29 Function-specific configfs interface
  30 ------------------------------------
  31
  32 The function name to use when creating the function directory is "acm".
  33 The ACM function provides just one attribute in its function directory:
  34
  35         port_num
  36
  37 The attribute is read-only.
  38
  39 There can be at most 4 ACM/generic serial/OBEX ports in the system.
  40
  41
  42 Testing the ACM function
  43 ------------------------
  44
  45 On the host: cat > /dev/ttyACM<X>
  46 On the device : cat /dev/ttyGS<Y>
  47
  48 then the other way round
  49
  50 On the device: cat > /dev/ttyGS<Y>
  51 On the host: cat /dev/ttyACM<X>
  52
  53 2. ECM function
  54 ===============
  55
  56 The function is provided by usb_f_ecm.ko module.
  57
  58 Function-specific configfs interface
  59 ------------------------------------
  60
  61 The function name to use when creating the function directory is "ecm".
  62 The ECM function provides these attributes in its function directory:
  63
  64         ifname          - network device interface name associated with this
  65                         function instance
  66         qmult           - queue length multiplier for high and super speed
  67         host_addr       - MAC address of host's end of this
  68                         Ethernet over USB link
  69         dev_addr        - MAC address of device's end of this
  70                         Ethernet over USB link
  71
  72 and after creating the functions/ecm.<instance name> they contain default
  73 values: qmult is 5, dev_addr and host_addr are randomly selected.
  74 Except for ifname they can be written to until the function is linked to a
  75 configuration. The ifname is read-only and contains the name of the interface
  76 which was assigned by the net core, e. g. usb0.
  77
  78 Testing the ECM function
  79 ------------------------
  80
  81 Configure IP addresses of the device and the host. Then:
  82
  83 On the device: ping <host's IP>
  84 On the host: ping <device's IP>
  85
  86 3. ECM subset function
  87 ======================
  88
  89 The function is provided by usb_f_ecm_subset.ko module.
  90
  91 Function-specific configfs interface
  92 ------------------------------------
  93
  94 The function name to use when creating the function directory is "geth".
  95 The ECM subset function provides these attributes in its function directory:
  96
  97         ifname          - network device interface name associated with this
  98                         function instance
  99         qmult           - queue length multiplier for high and super speed
 100         host_addr       - MAC address of host's end of this
 101                         Ethernet over USB link
 102         dev_addr        - MAC address of device's end of this
 103                         Ethernet over USB link
 104
 105 and after creating the functions/ecm.<instance name> they contain default
 106 values: qmult is 5, dev_addr and host_addr are randomly selected.
 107 Except for ifname they can be written to until the function is linked to a
 108 configuration. The ifname is read-only and contains the name of the interface
 109 which was assigned by the net core, e. g. usb0.
 110
 111 Testing the ECM subset function
 112 -------------------------------
 113
 114 Configure IP addresses of the device and the host. Then:
 115
 116 On the device: ping <host's IP>
 117 On the host: ping <device's IP>
 118
 119 4. EEM function
 120 ===============
 121
 122 The function is provided by usb_f_eem.ko module.
 123
 124 Function-specific configfs interface
 125 ------------------------------------
 126
 127 The function name to use when creating the function directory is "eem".
 128 The EEM function provides these attributes in its function directory:
 129
 130         ifname          - network device interface name associated with this
 131                         function instance
 132         qmult           - queue length multiplier for high and super speed
 133         host_addr       - MAC address of host's end of this
 134                         Ethernet over USB link
 135         dev_addr        - MAC address of device's end of this
 136                         Ethernet over USB link
 137
 138 and after creating the functions/eem.<instance name> they contain default
 139 values: qmult is 5, dev_addr and host_addr are randomly selected.
 140 Except for ifname they can be written to until the function is linked to a
 141 configuration. The ifname is read-only and contains the name of the interface
 142 which was assigned by the net core, e. g. usb0.
 143
 144 Testing the EEM function
 145 ------------------------
 146
 147 Configure IP addresses of the device and the host. Then:
 148
 149 On the device: ping <host's IP>
 150 On the host: ping <device's IP>
 151
 152 5. FFS function
 153 ===============
 154
 155 The function is provided by usb_f_fs.ko module.
 156
 157 Function-specific configfs interface
 158 ------------------------------------
 159
 160 The function name to use when creating the function directory is "ffs".
 161 The function directory is intentionally empty and not modifiable.
 162
 163 After creating the directory there is a new instance (a "device") of FunctionFS
 164 available in the system. Once a "device" is available, the user should follow
 165 the standard procedure for using FunctionFS (mount it, run the userspace
 166 process which implements the function proper). The gadget should be enabled
 167 by writing a suitable string to usb_gadget/<gadget>/UDC.
 168
 169 Testing the FFS function
 170 ------------------------
 171
 172 On the device: start the function's userspace daemon, enable the gadget
 173 On the host: use the USB function provided by the device
 174
 175 6. HID function
 176 ===============
 177
 178 The function is provided by usb_f_hid.ko module.
 179
 180 Function-specific configfs interface
 181 ------------------------------------
 182
 183 The function name to use when creating the function directory is "hid".
 184 The HID function provides these attributes in its function directory:
 185
 186         protocol        - HID protocol to use
 187         report_desc     - data to be used in HID reports, except data
 188                         passed with /dev/hidg<X>
 189         report_length   - HID report length
 190         subclass        - HID subclass to use
 191
 192 For a keyboard the protocol and the subclass are 1, the report_length is 8,
 193 while the report_desc is:
 194
 195 $ hd my_report_desc
 196 00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
 197 00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
 198 00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
 199 00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
 200 0000003f
 201
 202 Such a sequence of bytes can be stored to the attribute with echo:
 203
 204 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
 205
 206 Testing the HID function
 207 ------------------------
 208
 209 Device:
 210 - create the gadget
 211 - connect the gadget to a host, preferably not the one used
 212 to control the gadget
 213 - run a program which writes to /dev/hidg<N>, e.g.
 214 a userspace program found in Documentation/usb/gadget_hid.txt:
 215
 216 $ ./hid_gadget_test /dev/hidg0 keyboard
 217
 218 Host:
 219 - observe the keystrokes from the gadget
 220
 221 7. LOOPBACK function
 222 ====================
 223
 224 The function is provided by usb_f_ss_lb.ko module.
 225
 226 Function-specific configfs interface
 227 ------------------------------------
 228
 229 The function name to use when creating the function directory is "Loopback".
 230 The LOOPBACK function provides these attributes in its function directory:
 231
 232         qlen            - depth of loopback queue
 233         bulk_buflen     - buffer length
 234
 235 Testing the LOOPBACK function
 236 -----------------------------
 237
 238 device: run the gadget
 239 host: test-usb
 240
 241 http://www.linux-usb.org/usbtest/testusb.c
 242
 243 8. MASS STORAGE function
 244 ========================
 245
 246 The function is provided by usb_f_mass_storage.ko module.
 247
 248 Function-specific configfs interface
 249 ------------------------------------
 250
 251 The function name to use when creating the function directory is "mass_storage".
 252 The MASS STORAGE function provides these attributes in its directory:
 253 files:
 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
 262 and a default lun.0 directory corresponding to SCSI LUN #0.
 263
 264 A new lun can be added with mkdir:
 265
 266 $ mkdir functions/mass_storage.0/partition.5
 267
 268 Lun numbering does not have to be continuous, except for lun #0 which is
 269 created by default. A maximum of 8 luns can be specified and they all must be
 270 named following the <name>.<number> scheme. The numbers can be 0..8.
 271 Probably a good convention is to name the luns "lun.<number>",
 272 although it is not mandatory.
 273
 274 In 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
 289 Testing the MASS STORAGE function
 290 ---------------------------------
 291
 292 device: connect the gadget, enable it
 293 host: dmesg, see the USB drives appear (if system configured to automatically
 294 mount)
 295
 296 9. MIDI function
 297 ================
 298
 299 The function is provided by usb_f_midi.ko module.
 300
 301 Function-specific configfs interface
 302 ------------------------------------
 303
 304 The function name to use when creating the function directory is "midi".
 305 The 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
 314 Testing the MIDI function
 315 -------------------------
 316
 317 There are two cases: playing a mid from the gadget to
 318 the host and playing a mid from the host to the gadget.
 319
 320 1) Playing a mid from the gadget to the host
 321 host)
 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
 329 gadget)
 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
 337 2) Playing a mid from the host to the gadget
 338 gadget)
 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
 346 host)
 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
 355 The from_gadget.mid should sound identical to the to_host.mid.
 356 The from_host.id should sound identical to the to_gadget.mid.
 357
 358 MIDI 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
 364 128:0    TiMidity                         TiMidity port 0
 365 128:1    TiMidity                         TiMidity port 1
 366 128:2    TiMidity                         TiMidity port 2
 367 128:3    TiMidity                         TiMidity port 3
 368
 369 $ aplaymidi -p 128:0 file.mid
 370
 371 MIDI ports can be logically connected using the aconnect utility, e.g.:
 372
 373 $ aconnect 24:0 128:0 # try it on the host
 374
 375 After the gadget's MIDI port is connected to timidity's MIDI port,
 376 whatever is played at the gadget side with aplaymidi -l is audible
 377 in host's speakers/headphones.
 378
 379 10. NCM function
 380 ================
 381
 382 The function is provided by usb_f_ncm.ko module.
 383
 384 Function-specific configfs interface
 385 ------------------------------------
 386
 387 The function name to use when creating the function directory is "ncm".
 388 The 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
 398 and after creating the functions/ncm.<instance name> they contain default
 399 values: qmult is 5, dev_addr and host_addr are randomly selected.
 400 Except for ifname they can be written to until the function is linked to a
 401 configuration. The ifname is read-only and contains the name of the interface
 402 which was assigned by the net core, e. g. usb0.
 403
 404 Testing the NCM function
 405 ------------------------
 406
 407 Configure IP addresses of the device and the host. Then:
 408
 409 On the device: ping <host's IP>
 410 On the host: ping <device's IP>
 411
 412 11. OBEX function
 413 =================
 414
 415 The function is provided by usb_f_obex.ko module.
 416
 417 Function-specific configfs interface
 418 ------------------------------------
 419
 420 The function name to use when creating the function directory is "obex".
 421 The OBEX function provides just one attribute in its function directory:
 422
 423         port_num
 424
 425 The attribute is read-only.
 426
 427 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 428
 429 Testing the OBEX function
 430 -------------------------
 431
 432 On device: seriald -f /dev/ttyGS<Y> -s 1024
 433 On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
 434              -t<out endpoint addr> -r<in endpoint addr>
 435
 436 where seriald and serialc are Felipe's utilities found here:
 437
 438 https://git.gitorious.org/usb/usb-tools.git master
 439
 440 12. PHONET function
 441 ===================
 442
 443 The function is provided by usb_f_phonet.ko module.
 444
 445 Function-specific configfs interface
 446 ------------------------------------
 447
 448 The function name to use when creating the function directory is "phonet".
 449 The PHONET function provides just one attribute in its function directory:
 450
 451         ifname          - network device interface name associated with this
 452                         function instance
 453
 454 Testing the PHONET function
 455 ---------------------------
 456
 457 It is not possible to test the SOCK_STREAM protocol without a specific piece
 458 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
 459 in the past I had to apply the patch mentioned here:
 460
 461 http://www.spinics.net/lists/linux-usb/msg85689.html
 462
 463 These tools are required:
 464
 465 git://git.gitorious.org/meego-cellular/phonet-utils.git
 466
 467 On the host:
 468
 469 $ ./phonet -a 0x10 -i usbpn0
 470 $ ./pnroute add 0x6c usbpn0
 471 $./pnroute add 0x10 usbpn0
 472 $ ifconfig usbpn0 up
 473
 474 On the device:
 475
 476 $ ./phonet -a 0x6c -i upnlink0
 477 $ ./pnroute add 0x10 upnlink0
 478 $ ifconfig upnlink0 up
 479
 480 Then a test program can be used:
 481
 482 http://www.spinics.net/lists/linux-usb/msg85690.html
 483
 484 On the device:
 485
 486 $ ./pnxmit -a 0x6c -r
 487
 488 On the host:
 489
 490 $ ./pnxmit -a 0x10 -s 0x6c
 491
 492 As a result some data should be sent from host to device.
 493 Then the other way round:
 494
 495 On the host:
 496
 497 $ ./pnxmit -a 0x10 -r
 498
 499 On the device:
 500
 501 $ ./pnxmit -a 0x6c -s 0x10
 502
 503 13. RNDIS function
 504 ==================
 505
 506 The function is provided by usb_f_rndis.ko module.
 507
 508 Function-specific configfs interface
 509 ------------------------------------
 510
 511 The function name to use when creating the function directory is "rndis".
 512 The 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
 522 and after creating the functions/rndis.<instance name> they contain default
 523 values: qmult is 5, dev_addr and host_addr are randomly selected.
 524 Except for ifname they can be written to until the function is linked to a
 525 configuration. The ifname is read-only and contains the name of the interface
 526 which was assigned by the net core, e. g. usb0.
 527
 528 By default there can be only 1 RNDIS interface in the system.
 529
 530 Testing the RNDIS function
 531 --------------------------
 532
 533 Configure IP addresses of the device and the host. Then:
 534
 535 On the device: ping <host's IP>
 536 On the host: ping <device's IP>
 537
 538 14. SERIAL function
 539 ===================
 540
 541 The function is provided by usb_f_gser.ko module.
 542
 543 Function-specific configfs interface
 544 ------------------------------------
 545
 546 The function name to use when creating the function directory is "gser".
 547 The SERIAL function provides just one attribute in its function directory:
 548
 549         port_num
 550
 551 The attribute is read-only.
 552
 553 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 554
 555 Testing the SERIAL function
 556 ---------------------------
 557
 558 On host: insmod usbserial
 559          echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
 560 On host: cat > /dev/ttyUSB<X>
 561 On target: cat /dev/ttyGS<Y>
 562
 563 then the other way round
 564
 565 On target: cat > /dev/ttyGS<Y>
 566 On host: cat /dev/ttyUSB<X>
 567
 568 15. SOURCESINK function
 569 =======================
 570
 571 The function is provided by usb_f_ss_lb.ko module.
 572
 573 Function-specific configfs interface
 574 ------------------------------------
 575
 576 The function name to use when creating the function directory is "SourceSink".
 577 The SOURCESINK function provides these attributes in its function directory:
 578
 579         pattern         - 0 (all zeros), 1 (mod63), 2 (none)
 580         isoc_interval   - 1..16
 581         isoc_maxpacket  - 0 - 1023 (fs), 0 - 1024 (hs/ss)
 582         isoc_mult       - 0..2 (hs/ss only)
 583         isoc_maxburst   - 0..15 (ss only)
 584         bulk_buflen     - buffer length
 585
 586 Testing the SOURCESINK function
 587 -------------------------------
 588
 589 device: run the gadget
 590 host: test-usb
 591
 592 http://www.linux-usb.org/usbtest/testusb.c
 593
 594 16. UAC1 function
 595 =================
 596
 597 The function is provided by usb_f_uac1.ko module.
 598
 599 Function-specific configfs interface
 600 ------------------------------------
 601
 602 The function name to use when creating the function directory is "uac1".
 603 The 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
 612 The attributes have sane default values.
 613
 614 Testing the UAC1 function
 615 -------------------------
 616
 617 device: run the gadget
 618 host: aplay -l # should list our USB Audio Gadget
 619
 620 17. UAC2 function
 621 =================
 622
 623 The function is provided by usb_f_uac2.ko module.
 624
 625 Function-specific configfs interface
 626 ------------------------------------
 627
 628 The function name to use when creating the function directory is "uac2".
 629 The uac2 function provides these attributes in its function directory:
 630
 631         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
 638 The attributes have sane default values.
 639
 640 Testing the UAC2 function
 641 -------------------------
 642
 643 device: run the gadget
 644 host: aplay -l # should list our USB Audio Gadget
 645
 646 This function does not require real hardware support, it just
 647 sends a stream of audio data to/from the host. In order to
 648 actually hear something at the device side, a command similar
 649 to this must be used at the device side:
 650
 651 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
 652
 653 e.g.:
 654
 655 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
 656 aplay -D default:CARD=OdroidU3
 657
 658 18. UVC function
 659 ================
 660
 661 The function is provided by usb_f_uvc.ko module.
 662
 663 Function-specific configfs interface
 664 ------------------------------------
 665
 666 The function name to use when creating the function directory is "uvc".
 667 The uvc function provides these attributes in its function directory:
 668
 669         streaming_interval - interval for polling endpoint for data transfers
 670         streaming_maxburst - bMaxBurst for super speed companion descriptor
 671         streaming_maxpacket - maximum packet size this endpoint is capable of
 672                               sending or receiving when this configuration is
 673                               selected
 674
 675 There are also "control" and "streaming" subdirectories, each of which contain
 676 a number of their subdirectories. There are some sane defaults provided, but
 677 the user must provide the following:
 678
 679         control header - create in control/header, link from control/class/fs
 680                         and/or control/class/ss
 681         streaming header - create in streaming/header, link from
 682                         streaming/class/fs and/or streaming/class/hs and/or
 683                         streaming/class/ss
 684         format description - create in streaming/mjpeg and/or
 685                         streaming/uncompressed
 686         frame description - create in streaming/mjpeg/<format> and/or in
 687                         streaming/uncompressed/<format>
 688
 689 Each frame description contains frame interval specification, and each
 690 such specification consists of a number of lines with an inverval value
 691 in each line. The rules stated above are best illustrated with an example:
 692
 693 # mkdir functions/uvc.usb0/control/header/h
 694 # cd functions/uvc.usb0/control/header/h
 695 # ln -s header/h class/fs
 696 # ln -s header/h class/ss
 697 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
 698 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
 699 666666
 700 1000000
 701 5000000
 702 EOF
 703 # cd $GADGET_CONFIGFS_ROOT
 704 # mkdir functions/uvc.usb0/streaming/header/h
 705 # cd functions/uvc.usb0/streaming/header/h
 706 # ln -s ../../uncompressed/u
 707 # cd ../../class/fs
 708 # ln -s ../../header/h
 709 # cd ../../class/hs
 710 # ln -s ../../header/h
 711 # cd ../../class/ss
 712 # ln -s ../../header/h
 713
 714
 715 Testing the UVC function
 716 ------------------------
 717
 718 device: run the gadget, modprobe vivid
 719
 720 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
 721
 722 where uvc-gadget is this program:
 723 http://git.ideasonboard.org/uvc-gadget.git
 724
 725 with these patches:
 726 http://www.spinics.net/lists/linux-usb/msg99220.html
 727
 728 host: luvcview -f yuv