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
82static 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/*-------------------------------------------------------------------------*/
104USB_GADGET_COMPOSITE_OPTIONS();
105
106USB_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
146static 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
170static const struct usb_descriptor_header *otg_desc[2];
171
172static 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
179static struct usb_gadget_strings stringtab_dev = {
180	.language	= 0x0409,	/* en-us */
181	.strings	= strings_dev,
182};
183
184static struct usb_gadget_strings *dev_strings[] = {
185	&stringtab_dev,
186	NULL,
187};
188
189static struct usb_function_instance *fi_ecm;
190static struct usb_function *f_ecm;
191
192static struct usb_function_instance *fi_eem;
193static struct usb_function *f_eem;
194
195static struct usb_function_instance *fi_geth;
196static struct usb_function *f_geth;
197
198static struct usb_function_instance *fi_rndis;
199static 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 */
208static 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
230static 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
240static bool use_eem = 1;
241#else
242static bool use_eem;
243#endif
244module_param(use_eem, bool, 0);
245MODULE_PARM_DESC(use_eem, "use CDC EEM mode");
246
247/*
248 * We _always_ have an ECM, CDC Subset, or EEM configuration.
249 */
250static 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
295static 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
304static 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
433fail2:
434	kfree(otg_desc[0]);
435	otg_desc[0] = NULL;
436fail1:
437	if (has_rndis())
438		usb_put_function_instance(fi_rndis);
439fail:
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
449static 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
471static 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
480module_usb_composite_driver(eth_driver);
481
482MODULE_DESCRIPTION(PREFIX DRIVER_DESC);
483MODULE_AUTHOR("David Brownell, Benedikt Spanger");
484MODULE_LICENSE("GPL");
485