root/drivers/usb/gadget/legacy/ether.c

DEFINITIONS

1. has_rndis
2. rndis_do_config
3. eth_do_config
4. eth_bind
5. eth_unbind

   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(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  */
 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 
 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                         goto fail1;
 408                 usb_otg_descriptor_init(gadget, usb_desc);
 409                 otg_desc[0] = usb_desc;
 410                 otg_desc[1] = NULL;
 411         }
 412 
 413         /* register our configuration(s); RNDIS first, if it's used */
 414         if (has_rndis()) {
 415                 status = usb_add_config(cdev, &rndis_config_driver,
 416                                 rndis_do_config);
 417                 if (status < 0)
 418                         goto fail2;
 419         }
 420 
 421         status = usb_add_config(cdev, &eth_config_driver, eth_do_config);
 422         if (status < 0)
 423                 goto fail2;
 424 
 425         usb_composite_overwrite_options(cdev, &coverwrite);
 426         dev_info(&gadget->dev, "%s, version: " DRIVER_VERSION "\n",
 427                         DRIVER_DESC);
 428 
 429         return 0;
 430 
 431 fail2:
 432         kfree(otg_desc[0]);
 433         otg_desc[0] = NULL;
 434 fail1:
 435         if (has_rndis())
 436                 usb_put_function_instance(fi_rndis);
 437 fail:
 438         if (use_eem)
 439                 usb_put_function_instance(fi_eem);
 440         else if (can_support_ecm(gadget))
 441                 usb_put_function_instance(fi_ecm);
 442         else
 443                 usb_put_function_instance(fi_geth);
 444         return status;
 445 }
 446 
 447 static int eth_unbind(struct usb_composite_dev *cdev)
 448 {
 449         if (has_rndis()) {
 450                 usb_put_function(f_rndis);
 451                 usb_put_function_instance(fi_rndis);
 452         }
 453         if (use_eem) {
 454                 usb_put_function(f_eem);
 455                 usb_put_function_instance(fi_eem);
 456         } else if (can_support_ecm(cdev->gadget)) {
 457                 usb_put_function(f_ecm);
 458                 usb_put_function_instance(fi_ecm);
 459         } else {
 460                 usb_put_function(f_geth);
 461                 usb_put_function_instance(fi_geth);
 462         }
 463         kfree(otg_desc[0]);
 464         otg_desc[0] = NULL;
 465 
 466         return 0;
 467 }
 468 
 469 static struct usb_composite_driver eth_driver = {
 470         .name           = "g_ether",
 471         .dev            = &device_desc,
 472         .strings        = dev_strings,
 473         .max_speed      = USB_SPEED_SUPER,
 474         .bind           = eth_bind,
 475         .unbind         = eth_unbind,
 476 };
 477 
 478 module_usb_composite_driver(eth_driver);
 479 
 480 MODULE_DESCRIPTION(PREFIX DRIVER_DESC);
 481 MODULE_AUTHOR("David Brownell, Benedikt Spanger");
 482 MODULE_LICENSE("GPL");