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 | |
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 | */ |
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(g: c->cdev->gadget)) { |
215 | c->descriptors = otg_desc; |
216 | c->bmAttributes |= USB_CONFIG_ATT_WAKEUP; |
217 | } |
218 | |
219 | f_rndis = usb_get_function(fi: fi_rndis); |
220 | if (IS_ERR(ptr: f_rndis)) |
221 | return PTR_ERR(ptr: f_rndis); |
222 | |
223 | status = usb_add_function(c, f_rndis); |
224 | if (status < 0) |
225 | usb_put_function(f: 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 | */ |
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(g: 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: fi_eem); |
263 | if (IS_ERR(ptr: f_eem)) |
264 | return PTR_ERR(ptr: f_eem); |
265 | |
266 | status = usb_add_function(c, f_eem); |
267 | if (status < 0) |
268 | usb_put_function(f: f_eem); |
269 | |
270 | return status; |
271 | } else if (can_support_ecm(gadget: c->cdev->gadget)) { |
272 | f_ecm = usb_get_function(fi: fi_ecm); |
273 | if (IS_ERR(ptr: f_ecm)) |
274 | return PTR_ERR(ptr: f_ecm); |
275 | |
276 | status = usb_add_function(c, f_ecm); |
277 | if (status < 0) |
278 | usb_put_function(f: f_ecm); |
279 | |
280 | return status; |
281 | } else { |
282 | f_geth = usb_get_function(fi: fi_geth); |
283 | if (IS_ERR(ptr: f_geth)) |
284 | return PTR_ERR(ptr: f_geth); |
285 | |
286 | status = usb_add_function(c, f_geth); |
287 | if (status < 0) |
288 | usb_put_function(f: 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 | |
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(name: "eem" ); |
317 | if (IS_ERR(ptr: fi_eem)) |
318 | return PTR_ERR(ptr: 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(name: "ecm" ); |
331 | if (IS_ERR(ptr: fi_ecm)) |
332 | return PTR_ERR(ptr: 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(name: "geth" ); |
343 | if (IS_ERR(ptr: fi_geth)) |
344 | return PTR_ERR(ptr: 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, g: 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(name: "rndis" ); |
380 | if (IS_ERR(ptr: fi_rndis)) { |
381 | status = PTR_ERR(ptr: fi_rndis); |
382 | goto fail; |
383 | } |
384 | |
385 | rndis_borrow_net(f: 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(c: cdev, str: 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(g: 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, otg_desc: 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, ð_config_driver, eth_do_config); |
424 | if (status < 0) |
425 | goto fail2; |
426 | |
427 | usb_composite_overwrite_options(cdev, covr: &coverwrite); |
428 | dev_info(&gadget->dev, "%s, version: " DRIVER_VERSION "\n" , |
429 | DRIVER_DESC); |
430 | |
431 | return 0; |
432 | |
433 | fail2: |
434 | kfree(objp: otg_desc[0]); |
435 | otg_desc[0] = NULL; |
436 | fail1: |
437 | if (has_rndis()) |
438 | usb_put_function_instance(fi: fi_rndis); |
439 | fail: |
440 | if (use_eem) |
441 | usb_put_function_instance(fi: fi_eem); |
442 | else if (can_support_ecm(gadget)) |
443 | usb_put_function_instance(fi: fi_ecm); |
444 | else |
445 | usb_put_function_instance(fi: fi_geth); |
446 | return status; |
447 | } |
448 | |
449 | static int eth_unbind(struct usb_composite_dev *cdev) |
450 | { |
451 | if (has_rndis()) { |
452 | usb_put_function(f: f_rndis); |
453 | usb_put_function_instance(fi: fi_rndis); |
454 | } |
455 | if (use_eem) { |
456 | usb_put_function(f: f_eem); |
457 | usb_put_function_instance(fi: fi_eem); |
458 | } else if (can_support_ecm(gadget: cdev->gadget)) { |
459 | usb_put_function(f: f_ecm); |
460 | usb_put_function_instance(fi: fi_ecm); |
461 | } else { |
462 | usb_put_function(f: f_geth); |
463 | usb_put_function_instance(fi: fi_geth); |
464 | } |
465 | kfree(objp: 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 | |