[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


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
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
e38eb2c8 AP	11
	12
	13	1. ACM function
	14	===============
	15
	16	The function is provided by usb_f_acm.ko module.
	17
	18	Function-specific configfs interface
	19	------------------------------------
	20
	21	The function name to use when creating the function directory is "acm".
	22	The ACM function provides just one attribute in its function directory:
	23
	24	port_num
	25
	26	The attribute is read-only.
	27
	28	There can be at most 4 ACM/generic serial/OBEX ports in the system.
	29
	30
	31	Testing the ACM function
	32	------------------------
	33
	34	On the host: cat > /dev/ttyACM<X>
	35	On the device : cat /dev/ttyGS<Y>
	36
	37	then the other way round
	38
	39	On the device: cat > /dev/ttyGS<Y>
	40	On the host: cat /dev/ttyACM<X>
d5862ca6 AP	41
	42	2. ECM function
	43	===============
	44
	45	The function is provided by usb_f_ecm.ko module.
	46
	47	Function-specific configfs interface
	48	------------------------------------
	49
	50	The function name to use when creating the function directory is "ecm".
	51	The ECM function provides these attributes in its function directory:
	52
	53	ifname - network device interface name associated with this
	54	function instance
	55	qmult - queue length multiplier for high and super speed
	56	host_addr - MAC address of host's end of this
	57	Ethernet over USB link
	58	dev_addr - MAC address of device's end of this
	59	Ethernet over USB link
	60
	61	and after creating the functions/ecm.<instance name> they contain default
	62	values: qmult is 5, dev_addr and host_addr are randomly selected.
	63	Except for ifname they can be written to until the function is linked to a
	64	configuration. The ifname is read-only and contains the name of the interface
	65	which was assigned by the net core, e. g. usb0.
	66
	67	Testing the ECM function
	68	------------------------
	69
	70	Configure IP addresses of the device and the host. Then:
	71
	72	On the device: ping <host's IP>
	73	On the host: ping <device's IP>
7bfbc6e3 AP	74
	75	3. ECM subset function
	76	======================
	77
	78	The function is provided by usb_f_ecm_subset.ko module.
	79
	80	Function-specific configfs interface
	81	------------------------------------
	82
	83	The function name to use when creating the function directory is "geth".
	84	The ECM subset function provides these attributes in its function directory:
	85
	86	ifname - network device interface name associated with this
	87	function instance
	88	qmult - queue length multiplier for high and super speed
	89	host_addr - MAC address of host's end of this
	90	Ethernet over USB link
	91	dev_addr - MAC address of device's end of this
	92	Ethernet over USB link
	93
	94	and after creating the functions/ecm.<instance name> they contain default
	95	values: qmult is 5, dev_addr and host_addr are randomly selected.
	96	Except for ifname they can be written to until the function is linked to a
	97	configuration. The ifname is read-only and contains the name of the interface
	98	which was assigned by the net core, e. g. usb0.
	99
	100	Testing the ECM subset function
	101	-------------------------------
	102
	103	Configure IP addresses of the device and the host. Then:
	104
	105	On the device: ping <host's IP>
	106	On the host: ping <device's IP>
4ca560a6 AP	107
	108	4. EEM function
	109	===============
	110
	111	The function is provided by usb_f_eem.ko module.
	112
	113	Function-specific configfs interface
	114	------------------------------------
	115
	116	The function name to use when creating the function directory is "eem".
	117	The EEM function provides these attributes in its function directory:
	118
	119	ifname - network device interface name associated with this
	120	function instance
	121	qmult - queue length multiplier for high and super speed
	122	host_addr - MAC address of host's end of this
	123	Ethernet over USB link
	124	dev_addr - MAC address of device's end of this
	125	Ethernet over USB link
	126
	127	and after creating the functions/eem.<instance name> they contain default
	128	values: qmult is 5, dev_addr and host_addr are randomly selected.
	129	Except for ifname they can be written to until the function is linked to a
	130	configuration. The ifname is read-only and contains the name of the interface
	131	which was assigned by the net core, e. g. usb0.
	132
	133	Testing the EEM function
	134	------------------------
	135
	136	Configure IP addresses of the device and the host. Then:
	137
	138	On the device: ping <host's IP>
	139	On the host: ping <device's IP>
2c0f62f9 AP	140
	141	5. FFS function
	142	===============
	143
	144	The function is provided by usb_f_fs.ko module.
	145
	146	Function-specific configfs interface
	147	------------------------------------
	148
	149	The function name to use when creating the function directory is "ffs".
	150	The function directory is intentionally empty and not modifiable.
	151
	152	After creating the directory there is a new instance (a "device") of FunctionFS
	153	available in the system. Once a "device" is available, the user should follow
	154	the standard procedure for using FunctionFS (mount it, run the userspace
	155	process which implements the function proper). The gadget should be enabled
	156	by writing a suitable string to usb_gadget/<gadget>/UDC.
	157
	158	Testing the FFS function
	159	------------------------
	160
	161	On the device: start the function's userspace daemon, enable the gadget
	162	On the host: use the USB function provided by the device
f7e3c3cd AP	163
	164	6. HID function
	165	===============
	166
	167	The function is provided by usb_f_hid.ko module.
	168
	169	Function-specific configfs interface
	170	------------------------------------
	171
	172	The function name to use when creating the function directory is "hid".
	173	The HID function provides these attributes in its function directory:
	174
	175	protocol - HID protocol to use
	176	report_desc - data to be used in HID reports, except data
	177	passed with /dev/hidg<X>
	178	report_length - HID report length
	179	subclass - HID subclass to use
	180
	181	For a keyboard the protocol and the subclass are 1, the report_length is 8,
	182	while the report_desc is:
	183
	184	$ hd my_report_desc
	185	00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 \|..........)...%.\|
	186	00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 \|u.......u.....u.\|
	187	00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 \|....).....u.....\|
	188	00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 \|u...%e....)e...\|
	189	0000003f
	190
	191	Such a sequence of bytes can be stored to the attribute with echo:
	192
	193	$ echo -ne \\x05\\x01\\x09\\x06\\xa1.....
	194
	195	Testing the HID function
	196	------------------------
	197
	198	Device:
	199	- create the gadget
	200	- connect the gadget to a host, preferably not the one used
	201	to control the gadget
	202	- run a program which writes to /dev/hidg<N>, e.g.
	203	a userspace program found in Documentation/usb/gadget_hid.txt:
	204
	205	$ ./hid_gadget_test /dev/hidg0 keyboard
	206
	207	Host:
	208	- observe the keystrokes from the gadget
ec91aff7 AP	209
	210	7. LOOPBACK function
	211	====================
	212
	213	The function is provided by usb_f_ss_lb.ko module.
	214
	215	Function-specific configfs interface
	216	------------------------------------
	217
	218	The function name to use when creating the function directory is "Loopback".
	219	The LOOPBACK function provides these attributes in its function directory:
	220
	221	qlen - depth of loopback queue
	222	bulk_buflen - buffer length
	223
	224	Testing the LOOPBACK function
	225	-----------------------------
	226
	227	device: run the gadget
	228	host: test-usb
	229
	230	http://www.linux-usb.org/usbtest/testusb.c