4d0fa79e0e
Summary of how to test NCM function of USB gadget. Signed-off-by: Andrzej Pietrasiewicz <andrzej.p@samsung.com> Signed-off-by: Felipe Balbi <balbi@ti.com>
403 lines
12 KiB
Plaintext
403 lines
12 KiB
Plaintext
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
|
|
|
|
|
|
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>
|