xref: /openbmc/linux/drivers/usb/gadget/legacy/ether.c (revision 3e1f4a2e)
1 // SPDX-License-Identifier: GPL-2.0+
2 /*
3  * ether.c -- Ethernet gadget driver, with CDC and non-CDC options
4  *
5  * Copyright (C) 2003-2005,2008 David Brownell
6  * Copyright (C) 2003-2004 Robert Schwebel, Benedikt Spranger
7  * Copyright (C) 2008 Nokia Corporation
8  */
9 
10 /* #define VERBOSE_DEBUG */
11 
12 #include <linux/kernel.h>
13 #include <linux/netdevice.h>
14 
15 #if defined USB_ETH_RNDIS
16 #  undef USB_ETH_RNDIS
17 #endif
18 #ifdef CONFIG_USB_ETH_RNDIS
19 #  define USB_ETH_RNDIS y
20 #endif
21 
22 #include "u_ether.h"
23 
24 
25 /*
26  * Ethernet gadget driver -- with CDC and non-CDC options
27  * Builds on hardware support for a full duplex link.
28  *
29  * CDC Ethernet is the standard USB solution for sending Ethernet frames
30  * using USB.  Real hardware tends to use the same framing protocol but look
31  * different for control features.  This driver strongly prefers to use
32  * this USB-IF standard as its open-systems interoperability solution;
33  * most host side USB stacks (except from Microsoft) support it.
34  *
35  * This is sometimes called "CDC ECM" (Ethernet Control Model) to support
36  * TLA-soup.  "CDC ACM" (Abstract Control Model) is for modems, and a new
37  * "CDC EEM" (Ethernet Emulation Model) is starting to spread.
38  *
39  * There's some hardware that can't talk CDC ECM.  We make that hardware
40  * implement a "minimalist" vendor-agnostic CDC core:  same framing, but
41  * link-level setup only requires activating the configuration.  Only the
42  * endpoint descriptors, and product/vendor IDs, are relevant; no control
43  * operations are available.  Linux supports it, but other host operating
44  * systems may not.  (This is a subset of CDC Ethernet.)
45  *
46  * It turns out that if you add a few descriptors to that "CDC Subset",
47  * (Windows) host side drivers from MCCI can treat it as one submode of
48  * a proprietary scheme called "SAFE" ... without needing to know about
49  * specific product/vendor IDs.  So we do that, making it easier to use
50  * those MS-Windows drivers.  Those added descriptors make it resemble a
51  * CDC MDLM device, but they don't change device behavior at all.  (See
52  * MCCI Engineering report 950198 "SAFE Networking Functions".)
53  *
54  * A third option is also in use.  Rather than CDC Ethernet, or something
55  * simpler, Microsoft pushes their own approach: RNDIS.  The published
56  * RNDIS specs are ambiguous and appear to be incomplete, and are also
57  * needlessly complex.  They borrow more from CDC ACM than CDC ECM.
58  */
59 
60 #define DRIVER_DESC		"Ethernet Gadget"
61 #define DRIVER_VERSION		"Memorial Day 2008"
62 
63 #ifdef USB_ETH_RNDIS
64 #define PREFIX			"RNDIS/"
65 #else
66 #define PREFIX			""
67 #endif
68 
69 /*
70  * This driver aims for interoperability by using CDC ECM unless
71  *
72  *		can_support_ecm()
73  *
74  * returns false, in which case it supports the CDC Subset.  By default,
75  * that returns true; most hardware has no problems with CDC ECM, that's
76  * a good default.  Previous versions of this driver had no default; this
77  * version changes that, removing overhead for new controller support.
78  *
79  *	IF YOUR HARDWARE CAN'T SUPPORT CDC ECM, UPDATE THAT ROUTINE!
80  */
81 
has_rndis(void)82 static inline bool has_rndis(void)
83 {
84 #ifdef	USB_ETH_RNDIS
85 	return true;
86 #else
87 	return false;
88 #endif
89 }
90 
91 #include <linux/module.h>
92 
93 #include "u_ecm.h"
94 #include "u_gether.h"
95 #ifdef	USB_ETH_RNDIS
96 #include "u_rndis.h"
97 #include "rndis.h"
98 #else
99 #define rndis_borrow_net(...) do {} while (0)
100 #endif
101 #include "u_eem.h"
102 
103 /*-------------------------------------------------------------------------*/
104 USB_GADGET_COMPOSITE_OPTIONS();
105 
106 USB_ETHERNET_MODULE_PARAMETERS();
107 
108 /* DO NOT REUSE THESE IDs with a protocol-incompatible driver!!  Ever!!
109  * Instead:  allocate your own, using normal USB-IF procedures.
110  */
111 
112 /* Thanks to NetChip Technologies for donating this product ID.
113  * It's for devices with only CDC Ethernet configurations.
114  */
115 #define CDC_VENDOR_NUM		0x0525	/* NetChip */
116 #define CDC_PRODUCT_NUM		0xa4a1	/* Linux-USB Ethernet Gadget */
117 
118 /* For hardware that can't talk CDC, we use the same vendor ID that
119  * ARM Linux has used for ethernet-over-usb, both with sa1100 and
120  * with pxa250.  We're protocol-compatible, if the host-side drivers
121  * use the endpoint descriptors.  bcdDevice (version) is nonzero, so
122  * drivers that need to hard-wire endpoint numbers have a hook.
123  *
124  * The protocol is a minimal subset of CDC Ether, which works on any bulk
125  * hardware that's not deeply broken ... even on hardware that can't talk
126  * RNDIS (like SA-1100, with no interrupt endpoint, or anything that
127  * doesn't handle control-OUT).
128  */
129 #define	SIMPLE_VENDOR_NUM	0x049f
130 #define	SIMPLE_PRODUCT_NUM	0x505a
131 
132 /* For hardware that can talk RNDIS and either of the above protocols,
133  * use this ID ... the windows INF files will know it.  Unless it's
134  * used with CDC Ethernet, Linux 2.4 hosts will need updates to choose
135  * the non-RNDIS configuration.
136  */
137 #define RNDIS_VENDOR_NUM	0x0525	/* NetChip */
138 #define RNDIS_PRODUCT_NUM	0xa4a2	/* Ethernet/RNDIS Gadget */
139 
140 /* For EEM gadgets */
141 #define EEM_VENDOR_NUM		0x1d6b	/* Linux Foundation */
142 #define EEM_PRODUCT_NUM		0x0102	/* EEM Gadget */
143 
144 /*-------------------------------------------------------------------------*/
145 
146 static struct usb_device_descriptor device_desc = {
147 	.bLength =		sizeof device_desc,
148 	.bDescriptorType =	USB_DT_DEVICE,
149 
150 	/* .bcdUSB = DYNAMIC */
151 
152 	.bDeviceClass =		USB_CLASS_COMM,
153 	.bDeviceSubClass =	0,
154 	.bDeviceProtocol =	0,
155 	/* .bMaxPacketSize0 = f(hardware) */
156 
157 	/* Vendor and product id defaults change according to what configs
158 	 * we support.  (As does bNumConfigurations.)  These values can
159 	 * also be overridden by module parameters.
160 	 */
161 	.idVendor =		cpu_to_le16 (CDC_VENDOR_NUM),
162 	.idProduct =		cpu_to_le16 (CDC_PRODUCT_NUM),
163 	/* .bcdDevice = f(hardware) */
164 	/* .iManufacturer = DYNAMIC */
165 	/* .iProduct = DYNAMIC */
166 	/* NO SERIAL NUMBER */
167 	.bNumConfigurations =	1,
168 };
169 
170 static const struct usb_descriptor_header *otg_desc[2];
171 
172 static struct usb_string strings_dev[] = {
173 	[USB_GADGET_MANUFACTURER_IDX].s = "",
174 	[USB_GADGET_PRODUCT_IDX].s = PREFIX DRIVER_DESC,
175 	[USB_GADGET_SERIAL_IDX].s = "",
176 	{  } /* end of list */
177 };
178 
179 static struct usb_gadget_strings stringtab_dev = {
180 	.language	= 0x0409,	/* en-us */
181 	.strings	= strings_dev,
182 };
183 
184 static struct usb_gadget_strings *dev_strings[] = {
185 	&stringtab_dev,
186 	NULL,
187 };
188 
189 static struct usb_function_instance *fi_ecm;
190 static struct usb_function *f_ecm;
191 
192 static struct usb_function_instance *fi_eem;
193 static struct usb_function *f_eem;
194 
195 static struct usb_function_instance *fi_geth;
196 static struct usb_function *f_geth;
197 
198 static struct usb_function_instance *fi_rndis;
199 static struct usb_function *f_rndis;
200 
201 /*-------------------------------------------------------------------------*/
202 
203 /*
204  * We may not have an RNDIS configuration, but if we do it needs to be
205  * the first one present.  That's to make Microsoft's drivers happy,
206  * and to follow DOCSIS 1.0 (cable modem standard).
207  */
rndis_do_config(struct usb_configuration * c)208 static int rndis_do_config(struct usb_configuration *c)
209 {
210 	int status;
211 
212 	/* FIXME alloc iConfiguration string, set it in c->strings */
213 
214 	if (gadget_is_otg(c->cdev->gadget)) {
215 		c->descriptors = otg_desc;
216 		c->bmAttributes |= USB_CONFIG_ATT_WAKEUP;
217 	}
218 
219 	f_rndis = usb_get_function(fi_rndis);
220 	if (IS_ERR(f_rndis))
221 		return PTR_ERR(f_rndis);
222 
223 	status = usb_add_function(c, f_rndis);
224 	if (status < 0)
225 		usb_put_function(f_rndis);
226 
227 	return status;
228 }
229 
230 static struct usb_configuration rndis_config_driver = {
231 	.label			= "RNDIS",
232 	.bConfigurationValue	= 2,
233 	/* .iConfiguration = DYNAMIC */
234 	.bmAttributes		= USB_CONFIG_ATT_SELFPOWER,
235 };
236 
237 /*-------------------------------------------------------------------------*/
238 
239 #ifdef CONFIG_USB_ETH_EEM
240 static bool use_eem = 1;
241 #else
242 static bool use_eem;
243 #endif
244 module_param(use_eem, bool, 0);
245 MODULE_PARM_DESC(use_eem, "use CDC EEM mode");
246 
247 /*
248  * We _always_ have an ECM, CDC Subset, or EEM configuration.
249  */
eth_do_config(struct usb_configuration * c)250 static int eth_do_config(struct usb_configuration *c)
251 {
252 	int status = 0;
253 
254 	/* FIXME alloc iConfiguration string, set it in c->strings */
255 
256 	if (gadget_is_otg(c->cdev->gadget)) {
257 		c->descriptors = otg_desc;
258 		c->bmAttributes |= USB_CONFIG_ATT_WAKEUP;
259 	}
260 
261 	if (use_eem) {
262 		f_eem = usb_get_function(fi_eem);
263 		if (IS_ERR(f_eem))
264 			return PTR_ERR(f_eem);
265 
266 		status = usb_add_function(c, f_eem);
267 		if (status < 0)
268 			usb_put_function(f_eem);
269 
270 		return status;
271 	} else if (can_support_ecm(c->cdev->gadget)) {
272 		f_ecm = usb_get_function(fi_ecm);
273 		if (IS_ERR(f_ecm))
274 			return PTR_ERR(f_ecm);
275 
276 		status = usb_add_function(c, f_ecm);
277 		if (status < 0)
278 			usb_put_function(f_ecm);
279 
280 		return status;
281 	} else {
282 		f_geth = usb_get_function(fi_geth);
283 		if (IS_ERR(f_geth))
284 			return PTR_ERR(f_geth);
285 
286 		status = usb_add_function(c, f_geth);
287 		if (status < 0)
288 			usb_put_function(f_geth);
289 
290 		return status;
291 	}
292 
293 }
294 
295 static struct usb_configuration eth_config_driver = {
296 	/* .label = f(hardware) */
297 	.bConfigurationValue	= 1,
298 	/* .iConfiguration = DYNAMIC */
299 	.bmAttributes		= USB_CONFIG_ATT_SELFPOWER,
300 };
301 
302 /*-------------------------------------------------------------------------*/
303 
eth_bind(struct usb_composite_dev * cdev)304 static int eth_bind(struct usb_composite_dev *cdev)
305 {
306 	struct usb_gadget	*gadget = cdev->gadget;
307 	struct f_eem_opts	*eem_opts = NULL;
308 	struct f_ecm_opts	*ecm_opts = NULL;
309 	struct f_gether_opts	*geth_opts = NULL;
310 	struct net_device	*net;
311 	int			status;
312 
313 	/* set up main config label and device descriptor */
314 	if (use_eem) {
315 		/* EEM */
316 		fi_eem = usb_get_function_instance("eem");
317 		if (IS_ERR(fi_eem))
318 			return PTR_ERR(fi_eem);
319 
320 		eem_opts = container_of(fi_eem, struct f_eem_opts, func_inst);
321 
322 		net = eem_opts->net;
323 
324 		eth_config_driver.label = "CDC Ethernet (EEM)";
325 		device_desc.idVendor = cpu_to_le16(EEM_VENDOR_NUM);
326 		device_desc.idProduct = cpu_to_le16(EEM_PRODUCT_NUM);
327 	} else if (can_support_ecm(gadget)) {
328 		/* ECM */
329 
330 		fi_ecm = usb_get_function_instance("ecm");
331 		if (IS_ERR(fi_ecm))
332 			return PTR_ERR(fi_ecm);
333 
334 		ecm_opts = container_of(fi_ecm, struct f_ecm_opts, func_inst);
335 
336 		net = ecm_opts->net;
337 
338 		eth_config_driver.label = "CDC Ethernet (ECM)";
339 	} else {
340 		/* CDC Subset */
341 
342 		fi_geth = usb_get_function_instance("geth");
343 		if (IS_ERR(fi_geth))
344 			return PTR_ERR(fi_geth);
345 
346 		geth_opts = container_of(fi_geth, struct f_gether_opts,
347 					 func_inst);
348 
349 		net = geth_opts->net;
350 
351 		eth_config_driver.label = "CDC Subset/SAFE";
352 
353 		device_desc.idVendor = cpu_to_le16(SIMPLE_VENDOR_NUM);
354 		device_desc.idProduct = cpu_to_le16(SIMPLE_PRODUCT_NUM);
355 		if (!has_rndis())
356 			device_desc.bDeviceClass = USB_CLASS_VENDOR_SPEC;
357 	}
358 
359 	gether_set_qmult(net, qmult);
360 	if (!gether_set_host_addr(net, host_addr))
361 		pr_info("using host ethernet address: %s", host_addr);
362 	if (!gether_set_dev_addr(net, dev_addr))
363 		pr_info("using self ethernet address: %s", dev_addr);
364 
365 	if (has_rndis()) {
366 		/* RNDIS plus ECM-or-Subset */
367 		gether_set_gadget(net, cdev->gadget);
368 		status = gether_register_netdev(net);
369 		if (status)
370 			goto fail;
371 
372 		if (use_eem)
373 			eem_opts->bound = true;
374 		else if (can_support_ecm(gadget))
375 			ecm_opts->bound = true;
376 		else
377 			geth_opts->bound = true;
378 
379 		fi_rndis = usb_get_function_instance("rndis");
380 		if (IS_ERR(fi_rndis)) {
381 			status = PTR_ERR(fi_rndis);
382 			goto fail;
383 		}
384 
385 		rndis_borrow_net(fi_rndis, net);
386 
387 		device_desc.idVendor = cpu_to_le16(RNDIS_VENDOR_NUM);
388 		device_desc.idProduct = cpu_to_le16(RNDIS_PRODUCT_NUM);
389 		device_desc.bNumConfigurations = 2;
390 	}
391 
392 	/* Allocate string descriptor numbers ... note that string
393 	 * contents can be overridden by the composite_dev glue.
394 	 */
395 
396 	status = usb_string_ids_tab(cdev, strings_dev);
397 	if (status < 0)
398 		goto fail1;
399 	device_desc.iManufacturer = strings_dev[USB_GADGET_MANUFACTURER_IDX].id;
400 	device_desc.iProduct = strings_dev[USB_GADGET_PRODUCT_IDX].id;
401 
402 	if (gadget_is_otg(gadget) && !otg_desc[0]) {
403 		struct usb_descriptor_header *usb_desc;
404 
405 		usb_desc = usb_otg_descriptor_alloc(gadget);
406 		if (!usb_desc) {
407 			status = -ENOMEM;
408 			goto fail1;
409 		}
410 		usb_otg_descriptor_init(gadget, usb_desc);
411 		otg_desc[0] = usb_desc;
412 		otg_desc[1] = NULL;
413 	}
414 
415 	/* register our configuration(s); RNDIS first, if it's used */
416 	if (has_rndis()) {
417 		status = usb_add_config(cdev, &rndis_config_driver,
418 				rndis_do_config);
419 		if (status < 0)
420 			goto fail2;
421 	}
422 
423 	status = usb_add_config(cdev, &eth_config_driver, eth_do_config);
424 	if (status < 0)
425 		goto fail2;
426 
427 	usb_composite_overwrite_options(cdev, &coverwrite);
428 	dev_info(&gadget->dev, "%s, version: " DRIVER_VERSION "\n",
429 			DRIVER_DESC);
430 
431 	return 0;
432 
433 fail2:
434 	kfree(otg_desc[0]);
435 	otg_desc[0] = NULL;
436 fail1:
437 	if (has_rndis())
438 		usb_put_function_instance(fi_rndis);
439 fail:
440 	if (use_eem)
441 		usb_put_function_instance(fi_eem);
442 	else if (can_support_ecm(gadget))
443 		usb_put_function_instance(fi_ecm);
444 	else
445 		usb_put_function_instance(fi_geth);
446 	return status;
447 }
448 
eth_unbind(struct usb_composite_dev * cdev)449 static int eth_unbind(struct usb_composite_dev *cdev)
450 {
451 	if (has_rndis()) {
452 		usb_put_function(f_rndis);
453 		usb_put_function_instance(fi_rndis);
454 	}
455 	if (use_eem) {
456 		usb_put_function(f_eem);
457 		usb_put_function_instance(fi_eem);
458 	} else if (can_support_ecm(cdev->gadget)) {
459 		usb_put_function(f_ecm);
460 		usb_put_function_instance(fi_ecm);
461 	} else {
462 		usb_put_function(f_geth);
463 		usb_put_function_instance(fi_geth);
464 	}
465 	kfree(otg_desc[0]);
466 	otg_desc[0] = NULL;
467 
468 	return 0;
469 }
470 
471 static struct usb_composite_driver eth_driver = {
472 	.name		= "g_ether",
473 	.dev		= &device_desc,
474 	.strings	= dev_strings,
475 	.max_speed	= USB_SPEED_SUPER,
476 	.bind		= eth_bind,
477 	.unbind		= eth_unbind,
478 };
479 
480 module_usb_composite_driver(eth_driver);
481 
482 MODULE_DESCRIPTION(PREFIX DRIVER_DESC);
483 MODULE_AUTHOR("David Brownell, Benedikt Spanger");
484 MODULE_LICENSE("GPL");
485