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
  20
  21 1. ACM function
  22 ===============
  23
  24 The function is provided by usb_f_acm.ko module.
  25
  26 Function-specific configfs interface
  27 ------------------------------------
  28
  29 The function name to use when creating the function directory is "acm".
  30 The ACM function provides just one attribute in its function directory:
  31
  32         port_num
  33
  34 The attribute is read-only.
  35
  36 There can be at most 4 ACM/generic serial/OBEX ports in the system.
  37
  38
  39 Testing the ACM function
  40 ------------------------
  41
  42 On the host: cat > /dev/ttyACM<X>
  43 On the device : cat /dev/ttyGS<Y>
  44
  45 then the other way round
  46
  47 On the device: cat > /dev/ttyGS<Y>
  48 On the host: cat /dev/ttyACM<X>
  49
  50 2. ECM function
  51 ===============
  52
  53 The function is provided by usb_f_ecm.ko module.
  54
  55 Function-specific configfs interface
  56 ------------------------------------
  57
  58 The function name to use when creating the function directory is "ecm".
  59 The ECM function provides these attributes in its function directory:
  60
  61         ifname          - network device interface name associated with this
  62                         function instance
  63         qmult           - queue length multiplier for high and super speed
  64         host_addr       - MAC address of host's end of this
  65                         Ethernet over USB link
  66         dev_addr        - MAC address of device's end of this
  67                         Ethernet over USB link
  68
  69 and after creating the functions/ecm.<instance name> they contain default
  70 values: qmult is 5, dev_addr and host_addr are randomly selected.
  71 Except for ifname they can be written to until the function is linked to a
  72 configuration. The ifname is read-only and contains the name of the interface
  73 which was assigned by the net core, e. g. usb0.
  74
  75 Testing the ECM function
  76 ------------------------
  77
  78 Configure IP addresses of the device and the host. Then:
  79
  80 On the device: ping <host's IP>
  81 On the host: ping <device's IP>
  82
  83 3. ECM subset function
  84 ======================
  85
  86 The function is provided by usb_f_ecm_subset.ko module.
  87
  88 Function-specific configfs interface
  89 ------------------------------------
  90
  91 The function name to use when creating the function directory is "geth".
  92 The ECM subset function provides these attributes in its function directory:
  93
  94         ifname          - network device interface name associated with this
  95                         function instance
  96         qmult           - queue length multiplier for high and super speed
  97         host_addr       - MAC address of host's end of this
  98                         Ethernet over USB link
  99         dev_addr        - MAC address of device's end of this
 100                         Ethernet over USB link
 101
 102 and after creating the functions/ecm.<instance name> they contain default
 103 values: qmult is 5, dev_addr and host_addr are randomly selected.
 104 Except for ifname they can be written to until the function is linked to a
 105 configuration. The ifname is read-only and contains the name of the interface
 106 which was assigned by the net core, e. g. usb0.
 107
 108 Testing the ECM subset function
 109 -------------------------------
 110
 111 Configure IP addresses of the device and the host. Then:
 112
 113 On the device: ping <host's IP>
 114 On the host: ping <device's IP>
 115
 116 4. EEM function
 117 ===============
 118
 119 The function is provided by usb_f_eem.ko module.
 120
 121 Function-specific configfs interface
 122 ------------------------------------
 123
 124 The function name to use when creating the function directory is "eem".
 125 The EEM function provides these attributes in its function directory:
 126
 127         ifname          - network device interface name associated with this
 128                         function instance
 129         qmult           - queue length multiplier for high and super speed
 130         host_addr       - MAC address of host's end of this
 131                         Ethernet over USB link
 132         dev_addr        - MAC address of device's end of this
 133                         Ethernet over USB link
 134
 135 and after creating the functions/eem.<instance name> they contain default
 136 values: qmult is 5, dev_addr and host_addr are randomly selected.
 137 Except for ifname they can be written to until the function is linked to a
 138 configuration. The ifname is read-only and contains the name of the interface
 139 which was assigned by the net core, e. g. usb0.
 140
 141 Testing the EEM function
 142 ------------------------
 143
 144 Configure IP addresses of the device and the host. Then:
 145
 146 On the device: ping <host's IP>
 147 On the host: ping <device's IP>
 148
 149 5. FFS function
 150 ===============
 151
 152 The function is provided by usb_f_fs.ko module.
 153
 154 Function-specific configfs interface
 155 ------------------------------------
 156
 157 The function name to use when creating the function directory is "ffs".
 158 The function directory is intentionally empty and not modifiable.
 159
 160 After creating the directory there is a new instance (a "device") of FunctionFS
 161 available in the system. Once a "device" is available, the user should follow
 162 the standard procedure for using FunctionFS (mount it, run the userspace
 163 process which implements the function proper). The gadget should be enabled
 164 by writing a suitable string to usb_gadget/<gadget>/UDC.
 165
 166 Testing the FFS function
 167 ------------------------
 168
 169 On the device: start the function's userspace daemon, enable the gadget
 170 On the host: use the USB function provided by the device
 171
 172 6. HID function
 173 ===============
 174
 175 The function is provided by usb_f_hid.ko module.
 176
 177 Function-specific configfs interface
 178 ------------------------------------
 179
 180 The function name to use when creating the function directory is "hid".
 181 The HID function provides these attributes in its function directory:
 182
 183         protocol        - HID protocol to use
 184         report_desc     - data to be used in HID reports, except data
 185                         passed with /dev/hidg<X>
 186         report_length   - HID report length
 187         subclass        - HID subclass to use
 188
 189 For a keyboard the protocol and the subclass are 1, the report_length is 8,
 190 while the report_desc is:
 191
 192 $ hd my_report_desc
 193 00000000  05 01 09 06 a1 01 05 07  19 e0 29 e7 15 00 25 01  |..........)...%.|
 194 00000010  75 01 95 08 81 02 95 01  75 08 81 03 95 05 75 01  |u.......u.....u.|
 195 00000020  05 08 19 01 29 05 91 02  95 01 75 03 91 03 95 06  |....).....u.....|
 196 00000030  75 08 15 00 25 65 05 07  19 00 29 65 81 00 c0     |u...%e....)e...|
 197 0000003f
 198
 199 Such a sequence of bytes can be stored to the attribute with echo:
 200
 201 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
 202
 203 Testing the HID function
 204 ------------------------
 205
 206 Device:
 207 - create the gadget
 208 - connect the gadget to a host, preferably not the one used
 209 to control the gadget
 210 - run a program which writes to /dev/hidg<N>, e.g.
 211 a userspace program found in Documentation/usb/gadget_hid.txt:
 212
 213 $ ./hid_gadget_test /dev/hidg0 keyboard
 214
 215 Host:
 216 - observe the keystrokes from the gadget
 217
 218 7. LOOPBACK function
 219 ====================
 220
 221 The function is provided by usb_f_ss_lb.ko module.
 222
 223 Function-specific configfs interface
 224 ------------------------------------
 225
 226 The function name to use when creating the function directory is "Loopback".
 227 The LOOPBACK function provides these attributes in its function directory:
 228
 229         qlen            - depth of loopback queue
 230         bulk_buflen     - buffer length
 231
 232 Testing the LOOPBACK function
 233 -----------------------------
 234
 235 device: run the gadget
 236 host: test-usb
 237
 238 http://www.linux-usb.org/usbtest/testusb.c
 239
 240 8. MASS STORAGE function
 241 ========================
 242
 243 The function is provided by usb_f_mass_storage.ko module.
 244
 245 Function-specific configfs interface
 246 ------------------------------------
 247
 248 The function name to use when creating the function directory is "mass_storage".
 249 The MASS STORAGE function provides these attributes in its directory:
 250 files:
 251
 252         stall           - Set to permit function to halt bulk endpoints.
 253                         Disabled on some USB devices known not to work
 254                         correctly. You should set it to true.
 255         num_buffers     - Number of pipeline buffers. Valid numbers
 256                         are 2..4. Available only if
 257                         CONFIG_USB_GADGET_DEBUG_FILES is set.
 258
 259 and a default lun.0 directory corresponding to SCSI LUN #0.
 260
 261 A new lun can be added with mkdir:
 262
 263 $ mkdir functions/mass_storage.0/partition.5
 264
 265 Lun numbering does not have to be continuous, except for lun #0 which is
 266 created by default. A maximum of 8 luns can be specified and they all must be
 267 named following the <name>.<number> scheme. The numbers can be 0..8.
 268 Probably a good convention is to name the luns "lun.<number>",
 269 although it is not mandatory.
 270
 271 In each lun directory there are the following attribute files:
 272
 273         file            - The path to the backing file for the LUN.
 274                         Required if LUN is not marked as removable.
 275         ro              - Flag specifying access to the LUN shall be
 276                         read-only. This is implied if CD-ROM emulation
 277                         is enabled as well as when it was impossible
 278                         to open "filename" in R/W mode.
 279         removable       - Flag specifying that LUN shall be indicated as
 280                         being removable.
 281         cdrom           - Flag specifying that LUN shall be reported as
 282                         being a CD-ROM.
 283         nofua           - Flag specifying that FUA flag
 284                         in SCSI WRITE(10,12)
 285
 286 Testing the MASS STORAGE function
 287 ---------------------------------
 288
 289 device: connect the gadget, enable it
 290 host: dmesg, see the USB drives appear (if system configured to automatically
 291 mount)
 292
 293 9. MIDI function
 294 ================
 295
 296 The function is provided by usb_f_midi.ko module.
 297
 298 Function-specific configfs interface
 299 ------------------------------------
 300
 301 The function name to use when creating the function directory is "midi".
 302 The MIDI function provides these attributes in its function directory:
 303
 304         buflen          - MIDI buffer length
 305         id              - ID string for the USB MIDI adapter
 306         in_ports        - number of MIDI input ports
 307         index           - index value for the USB MIDI adapter
 308         out_ports       - number of MIDI output ports
 309         qlen            - USB read request queue length
 310
 311 Testing the MIDI function
 312 -------------------------
 313
 314 There are two cases: playing a mid from the gadget to
 315 the host and playing a mid from the host to the gadget.
 316
 317 1) Playing a mid from the gadget to the host
 318 host)
 319
 320 $ arecordmidi -l
 321  Port    Client name                      Port name
 322  14:0    Midi Through                     Midi Through Port-0
 323  24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 324 $ arecordmidi -p 24:0 from_gadget.mid
 325
 326 gadget)
 327
 328 $ aplaymidi -l
 329  Port    Client name                      Port name
 330  20:0    f_midi                           f_midi
 331
 332 $ aplaymidi -p 20:0 to_host.mid
 333
 334 2) Playing a mid from the host to the gadget
 335 gadget)
 336
 337 $ arecordmidi -l
 338  Port    Client name                      Port name
 339  20:0    f_midi                           f_midi
 340
 341 $ arecordmidi -p 20:0 from_host.mid
 342
 343 host)
 344
 345 $ aplaymidi -l
 346  Port    Client name                      Port name
 347  14:0    Midi Through                     Midi Through Port-0
 348  24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 349
 350 $ aplaymidi -p24:0 to_gadget.mid
 351
 352 The from_gadget.mid should sound identical to the to_host.mid.
 353 The from_host.id should sound identical to the to_gadget.mid.
 354
 355 MIDI files can be played to speakers/headphones with e.g. timidity installed
 356
 357 $ aplaymidi -l
 358  Port    Client name                      Port name
 359  14:0    Midi Through                     Midi Through Port-0
 360  24:0    MIDI Gadget                      MIDI Gadget MIDI 1
 361 128:0    TiMidity                         TiMidity port 0
 362 128:1    TiMidity                         TiMidity port 1
 363 128:2    TiMidity                         TiMidity port 2
 364 128:3    TiMidity                         TiMidity port 3
 365
 366 $ aplaymidi -p 128:0 file.mid
 367
 368 MIDI ports can be logically connected using the aconnect utility, e.g.:
 369
 370 $ aconnect 24:0 128:0 # try it on the host
 371
 372 After the gadget's MIDI port is connected to timidity's MIDI port,
 373 whatever is played at the gadget side with aplaymidi -l is audible
 374 in host's speakers/headphones.
 375
 376 10. NCM function
 377 ================
 378
 379 The function is provided by usb_f_ncm.ko module.
 380
 381 Function-specific configfs interface
 382 ------------------------------------
 383
 384 The function name to use when creating the function directory is "ncm".
 385 The NCM function provides these attributes in its function directory:
 386
 387         ifname          - network device interface name associated with this
 388                         function instance
 389         qmult           - queue length multiplier for high and super speed
 390         host_addr       - MAC address of host's end of this
 391                         Ethernet over USB link
 392         dev_addr        - MAC address of device's end of this
 393                         Ethernet over USB link
 394
 395 and after creating the functions/ncm.<instance name> they contain default
 396 values: qmult is 5, dev_addr and host_addr are randomly selected.
 397 Except for ifname they can be written to until the function is linked to a
 398 configuration. The ifname is read-only and contains the name of the interface
 399 which was assigned by the net core, e. g. usb0.
 400
 401 Testing the NCM function
 402 ------------------------
 403
 404 Configure IP addresses of the device and the host. Then:
 405
 406 On the device: ping <host's IP>
 407 On the host: ping <device's IP>
 408
 409 11. OBEX function
 410 =================
 411
 412 The function is provided by usb_f_obex.ko module.
 413
 414 Function-specific configfs interface
 415 ------------------------------------
 416
 417 The function name to use when creating the function directory is "obex".
 418 The OBEX function provides just one attribute in its function directory:
 419
 420         port_num
 421
 422 The attribute is read-only.
 423
 424 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 425
 426 Testing the OBEX function
 427 -------------------------
 428
 429 On device: seriald -f /dev/ttyGS<Y> -s 1024
 430 On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
 431              -t<out endpoint addr> -r<in endpoint addr>
 432
 433 where seriald and serialc are Felipe's utilities found here:
 434
 435 https://git.gitorious.org/usb/usb-tools.git master
 436
 437 12. PHONET function
 438 ===================
 439
 440 The function is provided by usb_f_phonet.ko module.
 441
 442 Function-specific configfs interface
 443 ------------------------------------
 444
 445 The function name to use when creating the function directory is "phonet".
 446 The PHONET function provides just one attribute in its function directory:
 447
 448         ifname          - network device interface name associated with this
 449                         function instance
 450
 451 Testing the PHONET function
 452 ---------------------------
 453
 454 It is not possible to test the SOCK_STREAM protocol without a specific piece
 455 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
 456 in the past I had to apply the patch mentioned here:
 457
 458 http://www.spinics.net/lists/linux-usb/msg85689.html
 459
 460 These tools are required:
 461
 462 git://git.gitorious.org/meego-cellular/phonet-utils.git
 463
 464 On the host:
 465
 466 $ ./phonet -a 0x10 -i usbpn0
 467 $ ./pnroute add 0x6c usbpn0
 468 $./pnroute add 0x10 usbpn0
 469 $ ifconfig usbpn0 up
 470
 471 On the device:
 472
 473 $ ./phonet -a 0x6c -i upnlink0
 474 $ ./pnroute add 0x10 upnlink0
 475 $ ifconfig upnlink0 up
 476
 477 Then a test program can be used:
 478
 479 http://www.spinics.net/lists/linux-usb/msg85690.html
 480
 481 On the device:
 482
 483 $ ./pnxmit -a 0x6c -r
 484
 485 On the host:
 486
 487 $ ./pnxmit -a 0x10 -s 0x6c
 488
 489 As a result some data should be sent from host to device.
 490 Then the other way round:
 491
 492 On the host:
 493
 494 $ ./pnxmit -a 0x10 -r
 495
 496 On the device:
 497
 498 $ ./pnxmit -a 0x6c -s 0x10
 499
 500 13. RNDIS function
 501 ==================
 502
 503 The function is provided by usb_f_rndis.ko module.
 504
 505 Function-specific configfs interface
 506 ------------------------------------
 507
 508 The function name to use when creating the function directory is "rndis".
 509 The RNDIS function provides these attributes in its function directory:
 510
 511         ifname          - network device interface name associated with this
 512                         function instance
 513         qmult           - queue length multiplier for high and super speed
 514         host_addr       - MAC address of host's end of this
 515                         Ethernet over USB link
 516         dev_addr        - MAC address of device's end of this
 517                         Ethernet over USB link
 518
 519 and after creating the functions/rndis.<instance name> they contain default
 520 values: qmult is 5, dev_addr and host_addr are randomly selected.
 521 Except for ifname they can be written to until the function is linked to a
 522 configuration. The ifname is read-only and contains the name of the interface
 523 which was assigned by the net core, e. g. usb0.
 524
 525 By default there can be only 1 RNDIS interface in the system.
 526
 527 Testing the RNDIS function
 528 --------------------------
 529
 530 Configure IP addresses of the device and the host. Then:
 531
 532 On the device: ping <host's IP>
 533 On the host: ping <device's IP>
 534
 535 14. SERIAL function
 536 ===================
 537
 538 The function is provided by usb_f_gser.ko module.
 539
 540 Function-specific configfs interface
 541 ------------------------------------
 542
 543 The function name to use when creating the function directory is "gser".
 544 The SERIAL function provides just one attribute in its function directory:
 545
 546         port_num
 547
 548 The attribute is read-only.
 549
 550 There can be at most 4 ACM/generic serial/OBEX ports in the system.
 551
 552 Testing the SERIAL function
 553 ---------------------------
 554
 555 On host: insmod usbserial
 556          echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
 557 On host: cat > /dev/ttyUSB<X>
 558 On target: cat /dev/ttyGS<Y>
 559
 560 then the other way round
 561
 562 On target: cat > /dev/ttyGS<Y>
 563 On host: cat /dev/ttyUSB<X>
 564
 565 15. SOURCESINK function
 566 =======================
 567
 568 The function is provided by usb_f_ss_lb.ko module.
 569
 570 Function-specific configfs interface
 571 ------------------------------------
 572
 573 The function name to use when creating the function directory is "SourceSink".
 574 The 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
 583 Testing the SOURCESINK function
 584 -------------------------------
 585
 586 device: run the gadget
 587 host: test-usb
 588
 589 http://www.linux-usb.org/usbtest/testusb.c