[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


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