| This file summarizes information on basic testing of USB functions |
| provided by gadgets. |
| |
| 1. ACM function |
| 2. ECM function |
| 3. ECM subset function |
| 4. EEM function |
| 5. FFS function |
| 6. HID function |
| 7. LOOPBACK function |
| 8. MASS STORAGE function |
| 9. MIDI function |
| 10. NCM function |
| 11. OBEX function |
| |
| |
| 1. ACM function |
| =============== |
| |
| The function is provided by usb_f_acm.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "acm". |
| The ACM function provides just one attribute in its function directory: |
| |
| port_num |
| |
| The attribute is read-only. |
| |
| There can be at most 4 ACM/generic serial/OBEX ports in the system. |
| |
| |
| Testing the ACM function |
| ------------------------ |
| |
| On the host: cat > /dev/ttyACM<X> |
| On the device : cat /dev/ttyGS<Y> |
| |
| then the other way round |
| |
| On the device: cat > /dev/ttyGS<Y> |
| On the host: cat /dev/ttyACM<X> |
| |
| 2. ECM function |
| =============== |
| |
| The function is provided by usb_f_ecm.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "ecm". |
| The ECM function provides these attributes in its function directory: |
| |
| ifname - network device interface name associated with this |
| function instance |
| qmult - queue length multiplier for high and super speed |
| host_addr - MAC address of host's end of this |
| Ethernet over USB link |
| dev_addr - MAC address of device's end of this |
| Ethernet over USB link |
| |
| and after creating the functions/ecm.<instance name> they contain default |
| values: qmult is 5, dev_addr and host_addr are randomly selected. |
| Except for ifname they can be written to until the function is linked to a |
| configuration. The ifname is read-only and contains the name of the interface |
| which was assigned by the net core, e. g. usb0. |
| |
| Testing the ECM function |
| ------------------------ |
| |
| Configure IP addresses of the device and the host. Then: |
| |
| On the device: ping <host's IP> |
| On the host: ping <device's IP> |
| |
| 3. ECM subset function |
| ====================== |
| |
| The function is provided by usb_f_ecm_subset.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "geth". |
| The ECM subset function provides these attributes in its function directory: |
| |
| ifname - network device interface name associated with this |
| function instance |
| qmult - queue length multiplier for high and super speed |
| host_addr - MAC address of host's end of this |
| Ethernet over USB link |
| dev_addr - MAC address of device's end of this |
| Ethernet over USB link |
| |
| and after creating the functions/ecm.<instance name> they contain default |
| values: qmult is 5, dev_addr and host_addr are randomly selected. |
| Except for ifname they can be written to until the function is linked to a |
| configuration. The ifname is read-only and contains the name of the interface |
| which was assigned by the net core, e. g. usb0. |
| |
| Testing the ECM subset function |
| ------------------------------- |
| |
| Configure IP addresses of the device and the host. Then: |
| |
| On the device: ping <host's IP> |
| On the host: ping <device's IP> |
| |
| 4. EEM function |
| =============== |
| |
| The function is provided by usb_f_eem.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "eem". |
| The EEM function provides these attributes in its function directory: |
| |
| ifname - network device interface name associated with this |
| function instance |
| qmult - queue length multiplier for high and super speed |
| host_addr - MAC address of host's end of this |
| Ethernet over USB link |
| dev_addr - MAC address of device's end of this |
| Ethernet over USB link |
| |
| and after creating the functions/eem.<instance name> they contain default |
| values: qmult is 5, dev_addr and host_addr are randomly selected. |
| Except for ifname they can be written to until the function is linked to a |
| configuration. The ifname is read-only and contains the name of the interface |
| which was assigned by the net core, e. g. usb0. |
| |
| Testing the EEM function |
| ------------------------ |
| |
| Configure IP addresses of the device and the host. Then: |
| |
| On the device: ping <host's IP> |
| On the host: ping <device's IP> |
| |
| 5. FFS function |
| =============== |
| |
| The function is provided by usb_f_fs.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "ffs". |
| The function directory is intentionally empty and not modifiable. |
| |
| After creating the directory there is a new instance (a "device") of FunctionFS |
| available in the system. Once a "device" is available, the user should follow |
| the standard procedure for using FunctionFS (mount it, run the userspace |
| process which implements the function proper). The gadget should be enabled |
| by writing a suitable string to usb_gadget/<gadget>/UDC. |
| |
| Testing the FFS function |
| ------------------------ |
| |
| On the device: start the function's userspace daemon, enable the gadget |
| On the host: use the USB function provided by the device |
| |
| 6. HID function |
| =============== |
| |
| The function is provided by usb_f_hid.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "hid". |
| The HID function provides these attributes in its function directory: |
| |
| protocol - HID protocol to use |
| report_desc - data to be used in HID reports, except data |
| passed with /dev/hidg<X> |
| report_length - HID report length |
| subclass - HID subclass to use |
| |
| For a keyboard the protocol and the subclass are 1, the report_length is 8, |
| while the report_desc is: |
| |
| $ hd my_report_desc |
| 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| |
| 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| |
| 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| |
| 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| |
| 0000003f |
| |
| Such a sequence of bytes can be stored to the attribute with echo: |
| |
| $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... |
| |
| Testing the HID function |
| ------------------------ |
| |
| Device: |
| - create the gadget |
| - connect the gadget to a host, preferably not the one used |
| to control the gadget |
| - run a program which writes to /dev/hidg<N>, e.g. |
| a userspace program found in Documentation/usb/gadget_hid.txt: |
| |
| $ ./hid_gadget_test /dev/hidg0 keyboard |
| |
| Host: |
| - observe the keystrokes from the gadget |
| |
| 7. LOOPBACK function |
| ==================== |
| |
| The function is provided by usb_f_ss_lb.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "Loopback". |
| The LOOPBACK function provides these attributes in its function directory: |
| |
| qlen - depth of loopback queue |
| bulk_buflen - buffer length |
| |
| Testing the LOOPBACK function |
| ----------------------------- |
| |
| device: run the gadget |
| host: test-usb |
| |
| http://www.linux-usb.org/usbtest/testusb.c |
| |
| 8. MASS STORAGE function |
| ======================== |
| |
| The function is provided by usb_f_mass_storage.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "mass_storage". |
| The MASS STORAGE function provides these attributes in its directory: |
| files: |
| |
| stall - Set to permit function to halt bulk endpoints. |
| Disabled on some USB devices known not to work |
| correctly. You should set it to true. |
| num_buffers - Number of pipeline buffers. Valid numbers |
| are 2..4. Available only if |
| CONFIG_USB_GADGET_DEBUG_FILES is set. |
| |
| and a default lun.0 directory corresponding to SCSI LUN #0. |
| |
| A new lun can be added with mkdir: |
| |
| $ mkdir functions/mass_storage.0/partition.5 |
| |
| Lun numbering does not have to be continuous, except for lun #0 which is |
| created by default. A maximum of 8 luns can be specified and they all must be |
| named following the <name>.<number> scheme. The numbers can be 0..8. |
| Probably a good convention is to name the luns "lun.<number>", |
| although it is not mandatory. |
| |
| In each lun directory there are the following attribute files: |
| |
| file - The path to the backing file for the LUN. |
| Required if LUN is not marked as removable. |
| ro - Flag specifying access to the LUN shall be |
| read-only. This is implied if CD-ROM emulation |
| is enabled as well as when it was impossible |
| to open "filename" in R/W mode. |
| removable - Flag specifying that LUN shall be indicated as |
| being removable. |
| cdrom - Flag specifying that LUN shall be reported as |
| being a CD-ROM. |
| nofua - Flag specifying that FUA flag |
| in SCSI WRITE(10,12) |
| |
| Testing the MASS STORAGE function |
| --------------------------------- |
| |
| device: connect the gadget, enable it |
| host: dmesg, see the USB drives appear (if system configured to automatically |
| mount) |
| |
| 9. MIDI function |
| ================ |
| |
| The function is provided by usb_f_midi.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "midi". |
| The MIDI function provides these attributes in its function directory: |
| |
| buflen - MIDI buffer length |
| id - ID string for the USB MIDI adapter |
| in_ports - number of MIDI input ports |
| index - index value for the USB MIDI adapter |
| out_ports - number of MIDI output ports |
| qlen - USB read request queue length |
| |
| Testing the MIDI function |
| ------------------------- |
| |
| There are two cases: playing a mid from the gadget to |
| the host and playing a mid from the host to the gadget. |
| |
| 1) Playing a mid from the gadget to the host |
| host) |
| |
| $ arecordmidi -l |
| Port Client name Port name |
| 14:0 Midi Through Midi Through Port-0 |
| 24:0 MIDI Gadget MIDI Gadget MIDI 1 |
| $ arecordmidi -p 24:0 from_gadget.mid |
| |
| gadget) |
| |
| $ aplaymidi -l |
| Port Client name Port name |
| 20:0 f_midi f_midi |
| |
| $ aplaymidi -p 20:0 to_host.mid |
| |
| 2) Playing a mid from the host to the gadget |
| gadget) |
| |
| $ arecordmidi -l |
| Port Client name Port name |
| 20:0 f_midi f_midi |
| |
| $ arecordmidi -p 20:0 from_host.mid |
| |
| host) |
| |
| $ aplaymidi -l |
| Port Client name Port name |
| 14:0 Midi Through Midi Through Port-0 |
| 24:0 MIDI Gadget MIDI Gadget MIDI 1 |
| |
| $ aplaymidi -p24:0 to_gadget.mid |
| |
| The from_gadget.mid should sound identical to the to_host.mid. |
| The from_host.id should sound identical to the to_gadget.mid. |
| |
| MIDI files can be played to speakers/headphones with e.g. timidity installed |
| |
| $ aplaymidi -l |
| Port Client name Port name |
| 14:0 Midi Through Midi Through Port-0 |
| 24:0 MIDI Gadget MIDI Gadget MIDI 1 |
| 128:0 TiMidity TiMidity port 0 |
| 128:1 TiMidity TiMidity port 1 |
| 128:2 TiMidity TiMidity port 2 |
| 128:3 TiMidity TiMidity port 3 |
| |
| $ aplaymidi -p 128:0 file.mid |
| |
| MIDI ports can be logically connected using the aconnect utility, e.g.: |
| |
| $ aconnect 24:0 128:0 # try it on the host |
| |
| After the gadget's MIDI port is connected to timidity's MIDI port, |
| whatever is played at the gadget side with aplaymidi -l is audible |
| in host's speakers/headphones. |
| |
| 10. NCM function |
| ================ |
| |
| The function is provided by usb_f_ncm.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "ncm". |
| The NCM function provides these attributes in its function directory: |
| |
| ifname - network device interface name associated with this |
| function instance |
| qmult - queue length multiplier for high and super speed |
| host_addr - MAC address of host's end of this |
| Ethernet over USB link |
| dev_addr - MAC address of device's end of this |
| Ethernet over USB link |
| |
| and after creating the functions/ncm.<instance name> they contain default |
| values: qmult is 5, dev_addr and host_addr are randomly selected. |
| Except for ifname they can be written to until the function is linked to a |
| configuration. The ifname is read-only and contains the name of the interface |
| which was assigned by the net core, e. g. usb0. |
| |
| Testing the NCM function |
| ------------------------ |
| |
| Configure IP addresses of the device and the host. Then: |
| |
| On the device: ping <host's IP> |
| On the host: ping <device's IP> |
| |
| 11. OBEX function |
| ================= |
| |
| The function is provided by usb_f_obex.ko module. |
| |
| Function-specific configfs interface |
| ------------------------------------ |
| |
| The function name to use when creating the function directory is "obex". |
| The OBEX function provides just one attribute in its function directory: |
| |
| port_num |
| |
| The attribute is read-only. |
| |
| There can be at most 4 ACM/generic serial/OBEX ports in the system. |
| |
| Testing the OBEX function |
| ------------------------- |
| |
| On device: seriald -f /dev/ttyGS<Y> -s 1024 |
| On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ |
| -t<out endpoint addr> -r<in endpoint addr> |
| |
| where seriald and serialc are Felipe's utilities found here: |
| |
| https://git.gitorious.org/usb/usb-tools.git master |