0001 ==============
0002 Gadget Testing
0003 ==============
0004
0005 This file summarizes information on basic testing of USB functions
0006 provided by gadgets.
0007
0008 .. contents
0009
0010 1. ACM function
0011 2. ECM function
0012 3. ECM subset function
0013 4. EEM function
0014 5. FFS function
0015 6. HID function
0016 7. LOOPBACK function
0017 8. MASS STORAGE function
0018 9. MIDI function
0019 10. NCM function
0020 11. OBEX function
0021 12. PHONET function
0022 13. RNDIS function
0023 14. SERIAL function
0024 15. SOURCESINK function
0025 16. UAC1 function (legacy implementation)
0026 17. UAC2 function
0027 18. UVC function
0028 19. PRINTER function
0029 20. UAC1 function (new API)
0030
0031
0032 1. ACM function
0033 ===============
0034
0035 The function is provided by usb_f_acm.ko module.
0036
0037 Function-specific configfs interface
0038 ------------------------------------
0039
0040 The function name to use when creating the function directory is "acm".
0041 The ACM function provides just one attribute in its function directory:
0042
0043 port_num
0044
0045 The attribute is read-only.
0046
0047 There can be at most 4 ACM/generic serial/OBEX ports in the system.
0048
0049
0050 Testing the ACM function
0051 ------------------------
0052
0053 On the host::
0054
0055 cat > /dev/ttyACM<X>
0056
0057 On the device::
0058
0059 cat /dev/ttyGS<Y>
0060
0061 then the other way round
0062
0063 On the device::
0064
0065 cat > /dev/ttyGS<Y>
0066
0067 On the host::
0068
0069 cat /dev/ttyACM<X>
0070
0071 2. ECM function
0072 ===============
0073
0074 The function is provided by usb_f_ecm.ko module.
0075
0076 Function-specific configfs interface
0077 ------------------------------------
0078
0079 The function name to use when creating the function directory is "ecm".
0080 The ECM function provides these attributes in its function directory:
0081
0082 =============== ==================================================
0083 ifname network device interface name associated with this
0084 function instance
0085 qmult queue length multiplier for high and super speed
0086 host_addr MAC address of host's end of this
0087 Ethernet over USB link
0088 dev_addr MAC address of device's end of this
0089 Ethernet over USB link
0090 =============== ==================================================
0091
0092 and after creating the functions/ecm.<instance name> they contain default
0093 values: qmult is 5, dev_addr and host_addr are randomly selected.
0094 The ifname can be written to if the function is not bound. A write must be an
0095 interface pattern such as "usb%d", which will cause the net core to choose the
0096 next free usbX interface. By default, it is set to "usb%d".
0097
0098 Testing the ECM function
0099 ------------------------
0100
0101 Configure IP addresses of the device and the host. Then:
0102
0103 On the device::
0104
0105 ping <host's IP>
0106
0107 On the host::
0108
0109 ping <device's IP>
0110
0111 3. ECM subset function
0112 ======================
0113
0114 The function is provided by usb_f_ecm_subset.ko module.
0115
0116 Function-specific configfs interface
0117 ------------------------------------
0118
0119 The function name to use when creating the function directory is "geth".
0120 The ECM subset function provides these attributes in its function directory:
0121
0122 =============== ==================================================
0123 ifname network device interface name associated with this
0124 function instance
0125 qmult queue length multiplier for high and super speed
0126 host_addr MAC address of host's end of this
0127 Ethernet over USB link
0128 dev_addr MAC address of device's end of this
0129 Ethernet over USB link
0130 =============== ==================================================
0131
0132 and after creating the functions/ecm.<instance name> they contain default
0133 values: qmult is 5, dev_addr and host_addr are randomly selected.
0134 The ifname can be written to if the function is not bound. A write must be an
0135 interface pattern such as "usb%d", which will cause the net core to choose the
0136 next free usbX interface. By default, it is set to "usb%d".
0137
0138 Testing the ECM subset function
0139 -------------------------------
0140
0141 Configure IP addresses of the device and the host. Then:
0142
0143 On the device::
0144
0145 ping <host's IP>
0146
0147 On the host::
0148
0149 ping <device's IP>
0150
0151 4. EEM function
0152 ===============
0153
0154 The function is provided by usb_f_eem.ko module.
0155
0156 Function-specific configfs interface
0157 ------------------------------------
0158
0159 The function name to use when creating the function directory is "eem".
0160 The EEM function provides these attributes in its function directory:
0161
0162 =============== ==================================================
0163 ifname network device interface name associated with this
0164 function instance
0165 qmult queue length multiplier for high and super speed
0166 host_addr MAC address of host's end of this
0167 Ethernet over USB link
0168 dev_addr MAC address of device's end of this
0169 Ethernet over USB link
0170 =============== ==================================================
0171
0172 and after creating the functions/eem.<instance name> they contain default
0173 values: qmult is 5, dev_addr and host_addr are randomly selected.
0174 The ifname can be written to if the function is not bound. A write must be an
0175 interface pattern such as "usb%d", which will cause the net core to choose the
0176 next free usbX interface. By default, it is set to "usb%d".
0177
0178 Testing the EEM function
0179 ------------------------
0180
0181 Configure IP addresses of the device and the host. Then:
0182
0183 On the device::
0184
0185 ping <host's IP>
0186
0187 On the host::
0188
0189 ping <device's IP>
0190
0191 5. FFS function
0192 ===============
0193
0194 The function is provided by usb_f_fs.ko module.
0195
0196 Function-specific configfs interface
0197 ------------------------------------
0198
0199 The function name to use when creating the function directory is "ffs".
0200 The function directory is intentionally empty and not modifiable.
0201
0202 After creating the directory there is a new instance (a "device") of FunctionFS
0203 available in the system. Once a "device" is available, the user should follow
0204 the standard procedure for using FunctionFS (mount it, run the userspace
0205 process which implements the function proper). The gadget should be enabled
0206 by writing a suitable string to usb_gadget/<gadget>/UDC.
0207
0208 Testing the FFS function
0209 ------------------------
0210
0211 On the device: start the function's userspace daemon, enable the gadget
0212
0213 On the host: use the USB function provided by the device
0214
0215 6. HID function
0216 ===============
0217
0218 The function is provided by usb_f_hid.ko module.
0219
0220 Function-specific configfs interface
0221 ------------------------------------
0222
0223 The function name to use when creating the function directory is "hid".
0224 The HID function provides these attributes in its function directory:
0225
0226 =============== ===========================================
0227 protocol HID protocol to use
0228 report_desc data to be used in HID reports, except data
0229 passed with /dev/hidg<X>
0230 report_length HID report length
0231 subclass HID subclass to use
0232 =============== ===========================================
0233
0234 For a keyboard the protocol and the subclass are 1, the report_length is 8,
0235 while the report_desc is::
0236
0237 $ hd my_report_desc
0238 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.|
0239 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.|
0240 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....|
0241 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...|
0242 0000003f
0243
0244 Such a sequence of bytes can be stored to the attribute with echo::
0245
0246 $ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
0247
0248 Testing the HID function
0249 ------------------------
0250
0251 Device:
0252
0253 - create the gadget
0254 - connect the gadget to a host, preferably not the one used
0255 to control the gadget
0256 - run a program which writes to /dev/hidg<N>, e.g.
0257 a userspace program found in Documentation/usb/gadget_hid.rst::
0258
0259 $ ./hid_gadget_test /dev/hidg0 keyboard
0260
0261 Host:
0262
0263 - observe the keystrokes from the gadget
0264
0265 7. LOOPBACK function
0266 ====================
0267
0268 The function is provided by usb_f_ss_lb.ko module.
0269
0270 Function-specific configfs interface
0271 ------------------------------------
0272
0273 The function name to use when creating the function directory is "Loopback".
0274 The LOOPBACK function provides these attributes in its function directory:
0275
0276 =============== =======================
0277 qlen depth of loopback queue
0278 bulk_buflen buffer length
0279 =============== =======================
0280
0281 Testing the LOOPBACK function
0282 -----------------------------
0283
0284 device: run the gadget
0285
0286 host: test-usb (tools/usb/testusb.c)
0287
0288 8. MASS STORAGE function
0289 ========================
0290
0291 The function is provided by usb_f_mass_storage.ko module.
0292
0293 Function-specific configfs interface
0294 ------------------------------------
0295
0296 The function name to use when creating the function directory is "mass_storage".
0297 The MASS STORAGE function provides these attributes in its directory:
0298 files:
0299
0300 =============== ==============================================
0301 stall Set to permit function to halt bulk endpoints.
0302 Disabled on some USB devices known not to work
0303 correctly. You should set it to true.
0304 num_buffers Number of pipeline buffers. Valid numbers
0305 are 2..4. Available only if
0306 CONFIG_USB_GADGET_DEBUG_FILES is set.
0307 =============== ==============================================
0308
0309 and a default lun.0 directory corresponding to SCSI LUN #0.
0310
0311 A new lun can be added with mkdir::
0312
0313 $ mkdir functions/mass_storage.0/partition.5
0314
0315 Lun numbering does not have to be continuous, except for lun #0 which is
0316 created by default. A maximum of 8 luns can be specified and they all must be
0317 named following the <name>.<number> scheme. The numbers can be 0..8.
0318 Probably a good convention is to name the luns "lun.<number>",
0319 although it is not mandatory.
0320
0321 In each lun directory there are the following attribute files:
0322
0323 =============== ==============================================
0324 file The path to the backing file for the LUN.
0325 Required if LUN is not marked as removable.
0326 ro Flag specifying access to the LUN shall be
0327 read-only. This is implied if CD-ROM emulation
0328 is enabled as well as when it was impossible
0329 to open "filename" in R/W mode.
0330 removable Flag specifying that LUN shall be indicated as
0331 being removable.
0332 cdrom Flag specifying that LUN shall be reported as
0333 being a CD-ROM.
0334 nofua Flag specifying that FUA flag
0335 in SCSI WRITE(10,12)
0336 forced_eject This write-only file is useful only when
0337 the function is active. It causes the backing
0338 file to be forcibly detached from the LUN,
0339 regardless of whether the host has allowed it.
0340 Any non-zero number of bytes written will
0341 result in ejection.
0342 =============== ==============================================
0343
0344 Testing the MASS STORAGE function
0345 ---------------------------------
0346
0347 device: connect the gadget, enable it
0348 host: dmesg, see the USB drives appear (if system configured to automatically
0349 mount)
0350
0351 9. MIDI function
0352 ================
0353
0354 The function is provided by usb_f_midi.ko module.
0355
0356 Function-specific configfs interface
0357 ------------------------------------
0358
0359 The function name to use when creating the function directory is "midi".
0360 The MIDI function provides these attributes in its function directory:
0361
0362 =============== ====================================
0363 buflen MIDI buffer length
0364 id ID string for the USB MIDI adapter
0365 in_ports number of MIDI input ports
0366 index index value for the USB MIDI adapter
0367 out_ports number of MIDI output ports
0368 qlen USB read request queue length
0369 =============== ====================================
0370
0371 Testing the MIDI function
0372 -------------------------
0373
0374 There are two cases: playing a mid from the gadget to
0375 the host and playing a mid from the host to the gadget.
0376
0377 1) Playing a mid from the gadget to the host:
0378
0379 host::
0380
0381 $ arecordmidi -l
0382 Port Client name Port name
0383 14:0 Midi Through Midi Through Port-0
0384 24:0 MIDI Gadget MIDI Gadget MIDI 1
0385 $ arecordmidi -p 24:0 from_gadget.mid
0386
0387 gadget::
0388
0389 $ aplaymidi -l
0390 Port Client name Port name
0391 20:0 f_midi f_midi
0392
0393 $ aplaymidi -p 20:0 to_host.mid
0394
0395 2) Playing a mid from the host to the gadget
0396
0397 gadget::
0398
0399 $ arecordmidi -l
0400 Port Client name Port name
0401 20:0 f_midi f_midi
0402
0403 $ arecordmidi -p 20:0 from_host.mid
0404
0405 host::
0406
0407 $ aplaymidi -l
0408 Port Client name Port name
0409 14:0 Midi Through Midi Through Port-0
0410 24:0 MIDI Gadget MIDI Gadget MIDI 1
0411
0412 $ aplaymidi -p24:0 to_gadget.mid
0413
0414 The from_gadget.mid should sound identical to the to_host.mid.
0415
0416 The from_host.id should sound identical to the to_gadget.mid.
0417
0418 MIDI files can be played to speakers/headphones with e.g. timidity installed::
0419
0420 $ aplaymidi -l
0421 Port Client name Port name
0422 14:0 Midi Through Midi Through Port-0
0423 24:0 MIDI Gadget MIDI Gadget MIDI 1
0424 128:0 TiMidity TiMidity port 0
0425 128:1 TiMidity TiMidity port 1
0426 128:2 TiMidity TiMidity port 2
0427 128:3 TiMidity TiMidity port 3
0428
0429 $ aplaymidi -p 128:0 file.mid
0430
0431 MIDI ports can be logically connected using the aconnect utility, e.g.::
0432
0433 $ aconnect 24:0 128:0 # try it on the host
0434
0435 After the gadget's MIDI port is connected to timidity's MIDI port,
0436 whatever is played at the gadget side with aplaymidi -l is audible
0437 in host's speakers/headphones.
0438
0439 10. NCM function
0440 ================
0441
0442 The function is provided by usb_f_ncm.ko module.
0443
0444 Function-specific configfs interface
0445 ------------------------------------
0446
0447 The function name to use when creating the function directory is "ncm".
0448 The NCM function provides these attributes in its function directory:
0449
0450 =============== ==================================================
0451 ifname network device interface name associated with this
0452 function instance
0453 qmult queue length multiplier for high and super speed
0454 host_addr MAC address of host's end of this
0455 Ethernet over USB link
0456 dev_addr MAC address of device's end of this
0457 Ethernet over USB link
0458 =============== ==================================================
0459
0460 and after creating the functions/ncm.<instance name> they contain default
0461 values: qmult is 5, dev_addr and host_addr are randomly selected.
0462 The ifname can be written to if the function is not bound. A write must be an
0463 interface pattern such as "usb%d", which will cause the net core to choose the
0464 next free usbX interface. By default, it is set to "usb%d".
0465
0466 Testing the NCM function
0467 ------------------------
0468
0469 Configure IP addresses of the device and the host. Then:
0470
0471 On the device::
0472
0473 ping <host's IP>
0474
0475 On the host::
0476
0477 ping <device's IP>
0478
0479 11. OBEX function
0480 =================
0481
0482 The function is provided by usb_f_obex.ko module.
0483
0484 Function-specific configfs interface
0485 ------------------------------------
0486
0487 The function name to use when creating the function directory is "obex".
0488 The OBEX function provides just one attribute in its function directory:
0489
0490 port_num
0491
0492 The attribute is read-only.
0493
0494 There can be at most 4 ACM/generic serial/OBEX ports in the system.
0495
0496 Testing the OBEX function
0497 -------------------------
0498
0499 On device::
0500
0501 seriald -f /dev/ttyGS<Y> -s 1024
0502
0503 On host::
0504
0505 serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \
0506 -t<out endpoint addr> -r<in endpoint addr>
0507
0508 where seriald and serialc are Felipe's utilities found here:
0509
0510 https://github.com/felipebalbi/usb-tools.git master
0511
0512 12. PHONET function
0513 ===================
0514
0515 The function is provided by usb_f_phonet.ko module.
0516
0517 Function-specific configfs interface
0518 ------------------------------------
0519
0520 The function name to use when creating the function directory is "phonet".
0521 The PHONET function provides just one attribute in its function directory:
0522
0523 =============== ==================================================
0524 ifname network device interface name associated with this
0525 function instance
0526 =============== ==================================================
0527
0528 Testing the PHONET function
0529 ---------------------------
0530
0531 It is not possible to test the SOCK_STREAM protocol without a specific piece
0532 of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
0533 in the past I had to apply the patch mentioned here:
0534
0535 http://www.spinics.net/lists/linux-usb/msg85689.html
0536
0537 These tools are required:
0538
0539 git://git.gitorious.org/meego-cellular/phonet-utils.git
0540
0541 On the host::
0542
0543 $ ./phonet -a 0x10 -i usbpn0
0544 $ ./pnroute add 0x6c usbpn0
0545 $./pnroute add 0x10 usbpn0
0546 $ ifconfig usbpn0 up
0547
0548 On the device::
0549
0550 $ ./phonet -a 0x6c -i upnlink0
0551 $ ./pnroute add 0x10 upnlink0
0552 $ ifconfig upnlink0 up
0553
0554 Then a test program can be used::
0555
0556 http://www.spinics.net/lists/linux-usb/msg85690.html
0557
0558 On the device::
0559
0560 $ ./pnxmit -a 0x6c -r
0561
0562 On the host::
0563
0564 $ ./pnxmit -a 0x10 -s 0x6c
0565
0566 As a result some data should be sent from host to device.
0567 Then the other way round:
0568
0569 On the host::
0570
0571 $ ./pnxmit -a 0x10 -r
0572
0573 On the device::
0574
0575 $ ./pnxmit -a 0x6c -s 0x10
0576
0577 13. RNDIS function
0578 ==================
0579
0580 The function is provided by usb_f_rndis.ko module.
0581
0582 Function-specific configfs interface
0583 ------------------------------------
0584
0585 The function name to use when creating the function directory is "rndis".
0586 The RNDIS function provides these attributes in its function directory:
0587
0588 =============== ==================================================
0589 ifname network device interface name associated with this
0590 function instance
0591 qmult queue length multiplier for high and super speed
0592 host_addr MAC address of host's end of this
0593 Ethernet over USB link
0594 dev_addr MAC address of device's end of this
0595 Ethernet over USB link
0596 =============== ==================================================
0597
0598 and after creating the functions/rndis.<instance name> they contain default
0599 values: qmult is 5, dev_addr and host_addr are randomly selected.
0600 The ifname can be written to if the function is not bound. A write must be an
0601 interface pattern such as "usb%d", which will cause the net core to choose the
0602 next free usbX interface. By default, it is set to "usb%d".
0603
0604 Testing the RNDIS function
0605 --------------------------
0606
0607 Configure IP addresses of the device and the host. Then:
0608
0609 On the device::
0610
0611 ping <host's IP>
0612
0613 On the host::
0614
0615 ping <device's IP>
0616
0617 14. SERIAL function
0618 ===================
0619
0620 The function is provided by usb_f_gser.ko module.
0621
0622 Function-specific configfs interface
0623 ------------------------------------
0624
0625 The function name to use when creating the function directory is "gser".
0626 The SERIAL function provides just one attribute in its function directory:
0627
0628 port_num
0629
0630 The attribute is read-only.
0631
0632 There can be at most 4 ACM/generic serial/OBEX ports in the system.
0633
0634 Testing the SERIAL function
0635 ---------------------------
0636
0637 On host::
0638
0639 insmod usbserial
0640 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
0641
0642 On host::
0643
0644 cat > /dev/ttyUSB<X>
0645
0646 On target::
0647
0648 cat /dev/ttyGS<Y>
0649
0650 then the other way round
0651
0652 On target::
0653
0654 cat > /dev/ttyGS<Y>
0655
0656 On host::
0657
0658 cat /dev/ttyUSB<X>
0659
0660 15. SOURCESINK function
0661 =======================
0662
0663 The function is provided by usb_f_ss_lb.ko module.
0664
0665 Function-specific configfs interface
0666 ------------------------------------
0667
0668 The function name to use when creating the function directory is "SourceSink".
0669 The SOURCESINK function provides these attributes in its function directory:
0670
0671 =============== ==================================
0672 pattern 0 (all zeros), 1 (mod63), 2 (none)
0673 isoc_interval 1..16
0674 isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss)
0675 isoc_mult 0..2 (hs/ss only)
0676 isoc_maxburst 0..15 (ss only)
0677 bulk_buflen buffer length
0678 bulk_qlen depth of queue for bulk
0679 iso_qlen depth of queue for iso
0680 =============== ==================================
0681
0682 Testing the SOURCESINK function
0683 -------------------------------
0684
0685 device: run the gadget
0686
0687 host: test-usb (tools/usb/testusb.c)
0688
0689
0690 16. UAC1 function (legacy implementation)
0691 =========================================
0692
0693 The function is provided by usb_f_uac1_legacy.ko module.
0694
0695 Function-specific configfs interface
0696 ------------------------------------
0697
0698 The function name to use when creating the function directory
0699 is "uac1_legacy".
0700 The uac1 function provides these attributes in its function directory:
0701
0702 =============== ====================================
0703 audio_buf_size audio buffer size
0704 fn_cap capture pcm device file name
0705 fn_cntl control device file name
0706 fn_play playback pcm device file name
0707 req_buf_size ISO OUT endpoint request buffer size
0708 req_count ISO OUT endpoint request count
0709 =============== ====================================
0710
0711 The attributes have sane default values.
0712
0713 Testing the UAC1 function
0714 -------------------------
0715
0716 device: run the gadget
0717
0718 host::
0719
0720 aplay -l # should list our USB Audio Gadget
0721
0722 17. UAC2 function
0723 =================
0724
0725 The function is provided by usb_f_uac2.ko module.
0726
0727 Function-specific configfs interface
0728 ------------------------------------
0729
0730 The function name to use when creating the function directory is "uac2".
0731 The uac2 function provides these attributes in its function directory:
0732
0733 ================ ====================================================
0734 c_chmask capture channel mask
0735 c_srate list of capture sampling rates (comma-separated)
0736 c_ssize capture sample size (bytes)
0737 c_sync capture synchronization type (async/adaptive)
0738 c_mute_present capture mute control enable
0739 c_volume_present capture volume control enable
0740 c_volume_min capture volume control min value (in 1/256 dB)
0741 c_volume_max capture volume control max value (in 1/256 dB)
0742 c_volume_res capture volume control resolution (in 1/256 dB)
0743 c_hs_bint capture bInterval for HS/SS (1-4: fixed, 0: auto)
0744 fb_max maximum extra bandwidth in async mode
0745 p_chmask playback channel mask
0746 p_srate list of playback sampling rates (comma-separated)
0747 p_ssize playback sample size (bytes)
0748 p_mute_present playback mute control enable
0749 p_volume_present playback volume control enable
0750 p_volume_min playback volume control min value (in 1/256 dB)
0751 p_volume_max playback volume control max value (in 1/256 dB)
0752 p_volume_res playback volume control resolution (in 1/256 dB)
0753 p_hs_bint playback bInterval for HS/SS (1-4: fixed, 0: auto)
0754 req_number the number of pre-allocated request for both capture
0755 and playback
0756 function_name name of the interface
0757 ================ ====================================================
0758
0759 The attributes have sane default values.
0760
0761 Testing the UAC2 function
0762 -------------------------
0763
0764 device: run the gadget
0765 host: aplay -l # should list our USB Audio Gadget
0766
0767 This function does not require real hardware support, it just
0768 sends a stream of audio data to/from the host. In order to
0769 actually hear something at the device side, a command similar
0770 to this must be used at the device side::
0771
0772 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
0773
0774 e.g.::
0775
0776 $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \
0777 aplay -D default:CARD=OdroidU3
0778
0779 18. UVC function
0780 ================
0781
0782 The function is provided by usb_f_uvc.ko module.
0783
0784 Function-specific configfs interface
0785 ------------------------------------
0786
0787 The function name to use when creating the function directory is "uvc".
0788 The uvc function provides these attributes in its function directory:
0789
0790 =================== ================================================
0791 streaming_interval interval for polling endpoint for data transfers
0792 streaming_maxburst bMaxBurst for super speed companion descriptor
0793 streaming_maxpacket maximum packet size this endpoint is capable of
0794 sending or receiving when this configuration is
0795 selected
0796 function_name name of the interface
0797 =================== ================================================
0798
0799 There are also "control" and "streaming" subdirectories, each of which contain
0800 a number of their subdirectories. There are some sane defaults provided, but
0801 the user must provide the following:
0802
0803 ================== ====================================================
0804 control header create in control/header, link from control/class/fs
0805 and/or control/class/ss
0806 streaming header create in streaming/header, link from
0807 streaming/class/fs and/or streaming/class/hs and/or
0808 streaming/class/ss
0809 format description create in streaming/mjpeg and/or
0810 streaming/uncompressed
0811 frame description create in streaming/mjpeg/<format> and/or in
0812 streaming/uncompressed/<format>
0813 ================== ====================================================
0814
0815 Each frame description contains frame interval specification, and each
0816 such specification consists of a number of lines with an inverval value
0817 in each line. The rules stated above are best illustrated with an example::
0818
0819 # mkdir functions/uvc.usb0/control/header/h
0820 # cd functions/uvc.usb0/control/
0821 # ln -s header/h class/fs
0822 # ln -s header/h class/ss
0823 # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p
0824 # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval
0825 666666
0826 1000000
0827 5000000
0828 EOF
0829 # cd $GADGET_CONFIGFS_ROOT
0830 # mkdir functions/uvc.usb0/streaming/header/h
0831 # cd functions/uvc.usb0/streaming/header/h
0832 # ln -s ../../uncompressed/u
0833 # cd ../../class/fs
0834 # ln -s ../../header/h
0835 # cd ../../class/hs
0836 # ln -s ../../header/h
0837 # cd ../../class/ss
0838 # ln -s ../../header/h
0839
0840
0841 Testing the UVC function
0842 ------------------------
0843
0844 device: run the gadget, modprobe vivid::
0845
0846 # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #>
0847
0848 where uvc-gadget is this program:
0849 http://git.ideasonboard.org/uvc-gadget.git
0850
0851 with these patches:
0852
0853 http://www.spinics.net/lists/linux-usb/msg99220.html
0854
0855 host::
0856
0857 luvcview -f yuv
0858
0859 19. PRINTER function
0860 ====================
0861
0862 The function is provided by usb_f_printer.ko module.
0863
0864 Function-specific configfs interface
0865 ------------------------------------
0866
0867 The function name to use when creating the function directory is "printer".
0868 The printer function provides these attributes in its function directory:
0869
0870 ========== ===========================================
0871 pnp_string Data to be passed to the host in pnp string
0872 q_len Number of requests per endpoint
0873 ========== ===========================================
0874
0875 Testing the PRINTER function
0876 ----------------------------
0877
0878 The most basic testing:
0879
0880 device: run the gadget::
0881
0882 # ls -l /devices/virtual/usb_printer_gadget/
0883
0884 should show g_printer<number>.
0885
0886 If udev is active, then /dev/g_printer<number> should appear automatically.
0887
0888 host:
0889
0890 If udev is active, then e.g. /dev/usb/lp0 should appear.
0891
0892 host->device transmission:
0893
0894 device::
0895
0896 # cat /dev/g_printer<number>
0897
0898 host::
0899
0900 # cat > /dev/usb/lp0
0901
0902 device->host transmission::
0903
0904 # cat > /dev/g_printer<number>
0905
0906 host::
0907
0908 # cat /dev/usb/lp0
0909
0910 More advanced testing can be done with the prn_example
0911 described in Documentation/usb/gadget_printer.rst.
0912
0913
0914 20. UAC1 function (virtual ALSA card, using u_audio API)
0915 ========================================================
0916
0917 The function is provided by usb_f_uac1.ko module.
0918 It will create a virtual ALSA card and the audio streams are simply
0919 sinked to and sourced from it.
0920
0921 Function-specific configfs interface
0922 ------------------------------------
0923
0924 The function name to use when creating the function directory is "uac1".
0925 The uac1 function provides these attributes in its function directory:
0926
0927 ================ ====================================================
0928 c_chmask capture channel mask
0929 c_srate list of capture sampling rates (comma-separated)
0930 c_ssize capture sample size (bytes)
0931 c_mute_present capture mute control enable
0932 c_volume_present capture volume control enable
0933 c_volume_min capture volume control min value (in 1/256 dB)
0934 c_volume_max capture volume control max value (in 1/256 dB)
0935 c_volume_res capture volume control resolution (in 1/256 dB)
0936 p_chmask playback channel mask
0937 p_srate list of playback sampling rates (comma-separated)
0938 p_ssize playback sample size (bytes)
0939 p_mute_present playback mute control enable
0940 p_volume_present playback volume control enable
0941 p_volume_min playback volume control min value (in 1/256 dB)
0942 p_volume_max playback volume control max value (in 1/256 dB)
0943 p_volume_res playback volume control resolution (in 1/256 dB)
0944 req_number the number of pre-allocated requests for both capture
0945 and playback
0946 function_name name of the interface
0947 ================ ====================================================
0948
0949 The attributes have sane default values.
0950
0951 Testing the UAC1 function
0952 -------------------------
0953
0954 device: run the gadget
0955 host: aplay -l # should list our USB Audio Gadget
0956
0957 This function does not require real hardware support, it just
0958 sends a stream of audio data to/from the host. In order to
0959 actually hear something at the device side, a command similar
0960 to this must be used at the device side::
0961
0962 $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
0963
0964 e.g.::
0965
0966 $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
0967 aplay -D default:CARD=OdroidU3
