[deliverable/linux.git] / Documentation / usb / gadget-testing.txt

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
12. PHONET function
13. RNDIS function
14. SERIAL 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

12. PHONET function
===================

The function is provided by usb_f_phonet.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "phonet".
The PHONET function provides just one attribute in its function directory:

	ifname		- network device interface name associated with this
			function instance

Testing the PHONET function
---------------------------

It is not possible to test the SOCK_STREAM protocol without a specific piece
of hardware, so only SOCK_DGRAM has been tested. For the latter to work,
in the past I had to apply the patch mentioned here:

http://www.spinics.net/lists/linux-usb/msg85689.html

These tools are required:

git://git.gitorious.org/meego-cellular/phonet-utils.git

On the host:

$ ./phonet -a 0x10 -i usbpn0
$ ./pnroute add 0x6c usbpn0
$./pnroute add 0x10 usbpn0
$ ifconfig usbpn0 up

On the device:

$ ./phonet -a 0x6c -i upnlink0
$ ./pnroute add 0x10 upnlink0
$ ifconfig upnlink0 up

Then a test program can be used:

http://www.spinics.net/lists/linux-usb/msg85690.html

On the device:

$ ./pnxmit -a 0x6c -r

On the host:

$ ./pnxmit -a 0x10 -s 0x6c

As a result some data should be sent from host to device.
Then the other way round:

On the host:

$ ./pnxmit -a 0x10 -r

On the device:

$ ./pnxmit -a 0x6c -s 0x10

13. RNDIS function
==================

The function is provided by usb_f_rndis.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "rndis".
The RNDIS 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/rndis.<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.

By default there can be only 1 RNDIS interface in the system.

Testing the RNDIS 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>

14. SERIAL function
===================

The function is provided by usb_f_gser.ko module.

Function-specific configfs interface
------------------------------------

The function name to use when creating the function directory is "gser".
The SERIAL 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 SERIAL function
---------------------------

On host: insmod usbserial
	 echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id
On host: cat > /dev/ttyUSB<X>
On target: cat /dev/ttyGS<Y>

then the other way round

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