drivers/usb/gadget/legacy/ether.c

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