drivers/usb/gadget/f_subset.c

   1 /*
   2  * f_subset.c -- "CDC Subset" Ethernet link function driver
   3  *
   4  * Copyright (C) 2003-2005,2008 David Brownell
   5  * Copyright (C) 2008 Nokia Corporation
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  */
  12
  13 #include <linux/slab.h>
  14 #include <linux/kernel.h>
  15 #include <linux/module.h>
  16 #include <linux/device.h>
  17 #include <linux/etherdevice.h>
  18
  19 #include "u_ether.h"
  20 #include "u_ether_configfs.h"
  21 #include "u_gether.h"
  22
  23 /*
  24  * This function packages a simple "CDC Subset" Ethernet port with no real
  25  * control mechanisms; just raw data transfer over two bulk endpoints.
  26  * The data transfer model is exactly that of CDC Ethernet, which is
  27  * why we call it the "CDC Subset".
  28  *
  29  * Because it's not standardized, this has some interoperability issues.
  30  * They mostly relate to driver binding, since the data transfer model is
  31  * so simple (CDC Ethernet).  The original versions of this protocol used
  32  * specific product/vendor IDs:  byteswapped IDs for Digital Equipment's
  33  * SA-1100 "Itsy" board, which could run Linux 2.4 kernels and supported
  34  * daughtercards with USB peripheral connectors.  (It was used more often
  35  * with other boards, using the Itsy identifiers.)  Linux hosts recognized
  36  * this with CONFIG_USB_ARMLINUX; these devices have only one configuration
  37  * and one interface.
  38  *
  39  * At some point, MCCI defined a (nonconformant) CDC MDLM variant called
  40  * "SAFE", which happens to have a mode which is identical to the "CDC
  41  * Subset" in terms of data transfer and lack of control model.  This was
  42  * adopted by later Sharp Zaurus models, and by some other software which
  43  * Linux hosts recognize with CONFIG_USB_NET_ZAURUS.
  44  *
  45  * Because Microsoft's RNDIS drivers are far from robust, we added a few
  46  * descriptors to the CDC Subset code, making this code look like a SAFE
  47  * implementation.  This lets you use MCCI's host side MS-Windows drivers
  48  * if you get fed up with RNDIS.  It also makes it easier for composite
  49  * drivers to work, since they can use class based binding instead of
  50  * caring about specific product and vendor IDs.
  51  */
  52
  53 struct f_gether {
  54         struct gether                   port;
  55
  56         char                            ethaddr[14];
  57 };
  58
  59 static inline struct f_gether *func_to_geth(struct usb_function *f)
  60 {
  61         return container_of(f, struct f_gether, port.func);
  62 }
  63
  64 /*-------------------------------------------------------------------------*/
  65
  66 /*
  67  * "Simple" CDC-subset option is a simple vendor-neutral model that most
  68  * full speed controllers can handle:  one interface, two bulk endpoints.
  69  * To assist host side drivers, we fancy it up a bit, and add descriptors so
  70  * some host side drivers will understand it as a "SAFE" variant.
  71  *
  72  * "SAFE" loosely follows CDC WMC MDLM, violating the spec in various ways.
  73  * Data endpoints live in the control interface, there's no data interface.
  74  * And it's not used to talk to a cell phone radio.
  75  */
  76
  77 /* interface descriptor: */
  78
  79 static struct usb_interface_descriptor subset_data_intf = {
  80         .bLength =              sizeof subset_data_intf,
  81         .bDescriptorType =      USB_DT_INTERFACE,
  82
  83         /* .bInterfaceNumber = DYNAMIC */
  84         .bAlternateSetting =    0,
  85         .bNumEndpoints =        2,
  86         .bInterfaceClass =      USB_CLASS_COMM,
  87         .bInterfaceSubClass =   USB_CDC_SUBCLASS_MDLM,
  88         .bInterfaceProtocol =   0,
  89         /* .iInterface = DYNAMIC */
  90 };
  91
  92 static struct usb_cdc_header_desc mdlm_header_desc = {
  93         .bLength =              sizeof mdlm_header_desc,
  94         .bDescriptorType =      USB_DT_CS_INTERFACE,
  95         .bDescriptorSubType =   USB_CDC_HEADER_TYPE,
  96
  97         .bcdCDC =               cpu_to_le16(0x0110),
  98 };
  99
 100 static struct usb_cdc_mdlm_desc mdlm_desc = {
 101         .bLength =              sizeof mdlm_desc,
 102         .bDescriptorType =      USB_DT_CS_INTERFACE,
 103         .bDescriptorSubType =   USB_CDC_MDLM_TYPE,
 104
 105         .bcdVersion =           cpu_to_le16(0x0100),
 106         .bGUID = {
 107                 0x5d, 0x34, 0xcf, 0x66, 0x11, 0x18, 0x11, 0xd6,
 108                 0xa2, 0x1a, 0x00, 0x01, 0x02, 0xca, 0x9a, 0x7f,
 109         },
 110 };
 111
 112 /* since "usb_cdc_mdlm_detail_desc" is a variable length structure, we
 113  * can't really use its struct.  All we do here is say that we're using
 114  * the submode of "SAFE" which directly matches the CDC Subset.
 115  */
 116 static u8 mdlm_detail_desc[] = {
 117         6,
 118         USB_DT_CS_INTERFACE,
 119         USB_CDC_MDLM_DETAIL_TYPE,
 120
 121         0,      /* "SAFE" */
 122         0,      /* network control capabilities (none) */
 123         0,      /* network data capabilities ("raw" encapsulation) */
 124 };
 125
 126 static struct usb_cdc_ether_desc ether_desc = {
 127         .bLength =              sizeof ether_desc,
 128         .bDescriptorType =      USB_DT_CS_INTERFACE,
 129         .bDescriptorSubType =   USB_CDC_ETHERNET_TYPE,
 130
 131         /* this descriptor actually adds value, surprise! */
 132         /* .iMACAddress = DYNAMIC */
 133         .bmEthernetStatistics = cpu_to_le32(0), /* no statistics */
 134         .wMaxSegmentSize =      cpu_to_le16(ETH_FRAME_LEN),
 135         .wNumberMCFilters =     cpu_to_le16(0),
 136         .bNumberPowerFilters =  0,
 137 };
 138
 139 /* full speed support: */
 140
 141 static struct usb_endpoint_descriptor fs_subset_in_desc = {
 142         .bLength =              USB_DT_ENDPOINT_SIZE,
 143         .bDescriptorType =      USB_DT_ENDPOINT,
 144
 145         .bEndpointAddress =     USB_DIR_IN,
 146         .bmAttributes =         USB_ENDPOINT_XFER_BULK,
 147 };
 148
 149 static struct usb_endpoint_descriptor fs_subset_out_desc = {
 150         .bLength =              USB_DT_ENDPOINT_SIZE,
 151         .bDescriptorType =      USB_DT_ENDPOINT,
 152
 153         .bEndpointAddress =     USB_DIR_OUT,
 154         .bmAttributes =         USB_ENDPOINT_XFER_BULK,
 155 };
 156
 157 static struct usb_descriptor_header *fs_eth_function[] = {
 158         (struct usb_descriptor_header *) &subset_data_intf,
 159         (struct usb_descriptor_header *) &mdlm_header_desc,
 160         (struct usb_descriptor_header *) &mdlm_desc,
 161         (struct usb_descriptor_header *) &mdlm_detail_desc,
 162         (struct usb_descriptor_header *) &ether_desc,
 163         (struct usb_descriptor_header *) &fs_subset_in_desc,
 164         (struct usb_descriptor_header *) &fs_subset_out_desc,
 165         NULL,
 166 };
 167
 168 /* high speed support: */
 169
 170 static struct usb_endpoint_descriptor hs_subset_in_desc = {
 171         .bLength =              USB_DT_ENDPOINT_SIZE,
 172         .bDescriptorType =      USB_DT_ENDPOINT,
 173
 174         .bmAttributes =         USB_ENDPOINT_XFER_BULK,
 175         .wMaxPacketSize =       cpu_to_le16(512),
 176 };
 177
 178 static struct usb_endpoint_descriptor hs_subset_out_desc = {
 179         .bLength =              USB_DT_ENDPOINT_SIZE,
 180         .bDescriptorType =      USB_DT_ENDPOINT,
 181
 182         .bmAttributes =         USB_ENDPOINT_XFER_BULK,
 183         .wMaxPacketSize =       cpu_to_le16(512),
 184 };
 185
 186 static struct usb_descriptor_header *hs_eth_function[] = {
 187         (struct usb_descriptor_header *) &subset_data_intf,
 188         (struct usb_descriptor_header *) &mdlm_header_desc,
 189         (struct usb_descriptor_header *) &mdlm_desc,
 190         (struct usb_descriptor_header *) &mdlm_detail_desc,
 191         (struct usb_descriptor_header *) &ether_desc,
 192         (struct usb_descriptor_header *) &hs_subset_in_desc,
 193         (struct usb_descriptor_header *) &hs_subset_out_desc,
 194         NULL,
 195 };
 196
 197 /* super speed support: */
 198
 199 static struct usb_endpoint_descriptor ss_subset_in_desc = {
 200         .bLength =              USB_DT_ENDPOINT_SIZE,
 201         .bDescriptorType =      USB_DT_ENDPOINT,
 202
 203         .bmAttributes =         USB_ENDPOINT_XFER_BULK,
 204         .wMaxPacketSize =       cpu_to_le16(1024),
 205 };
 206
 207 static struct usb_endpoint_descriptor ss_subset_out_desc = {
 208         .bLength =              USB_DT_ENDPOINT_SIZE,
 209         .bDescriptorType =      USB_DT_ENDPOINT,
 210
 211         .bmAttributes =         USB_ENDPOINT_XFER_BULK,
 212         .wMaxPacketSize =       cpu_to_le16(1024),
 213 };
 214
 215 static struct usb_ss_ep_comp_descriptor ss_subset_bulk_comp_desc = {
 216         .bLength =              sizeof ss_subset_bulk_comp_desc,
 217         .bDescriptorType =      USB_DT_SS_ENDPOINT_COMP,
 218
 219         /* the following 2 values can be tweaked if necessary */
 220         /* .bMaxBurst =         0, */
 221         /* .bmAttributes =      0, */
 222 };
 223
 224 static struct usb_descriptor_header *ss_eth_function[] = {
 225         (struct usb_descriptor_header *) &subset_data_intf,
 226         (struct usb_descriptor_header *) &mdlm_header_desc,
 227         (struct usb_descriptor_header *) &mdlm_desc,
 228         (struct usb_descriptor_header *) &mdlm_detail_desc,
 229         (struct usb_descriptor_header *) &ether_desc,
 230         (struct usb_descriptor_header *) &ss_subset_in_desc,
 231         (struct usb_descriptor_header *) &ss_subset_bulk_comp_desc,
 232         (struct usb_descriptor_header *) &ss_subset_out_desc,
 233         (struct usb_descriptor_header *) &ss_subset_bulk_comp_desc,
 234         NULL,
 235 };
 236
 237 /* string descriptors: */
 238
 239 static struct usb_string geth_string_defs[] = {
 240         [0].s = "CDC Ethernet Subset/SAFE",
 241         [1].s = "",
 242         {  } /* end of list */
 243 };
 244
 245 static struct usb_gadget_strings geth_string_table = {
 246         .language =             0x0409, /* en-us */
 247         .strings =              geth_string_defs,
 248 };
 249
 250 static struct usb_gadget_strings *geth_strings[] = {
 251         &geth_string_table,
 252         NULL,
 253 };
 254
 255 /*-------------------------------------------------------------------------*/
 256
 257 static int geth_set_alt(struct usb_function *f, unsigned intf, unsigned alt)
 258 {
 259         struct f_gether         *geth = func_to_geth(f);
 260         struct usb_composite_dev *cdev = f->config->cdev;
 261         struct net_device       *net;
 262
 263         /* we know alt == 0, so this is an activation or a reset */
 264
 265         if (geth->port.in_ep->driver_data) {
 266                 DBG(cdev, "reset cdc subset\n");
 267                 gether_disconnect(&geth->port);
 268         }
 269
 270         DBG(cdev, "init + activate cdc subset\n");
 271         if (config_ep_by_speed(cdev->gadget, f, geth->port.in_ep) ||
 272             config_ep_by_speed(cdev->gadget, f, geth->port.out_ep)) {
 273                 geth->port.in_ep->desc = NULL;
 274                 geth->port.out_ep->desc = NULL;
 275                 return -EINVAL;
 276         }
 277
 278         net = gether_connect(&geth->port);
 279         return IS_ERR(net) ? PTR_ERR(net) : 0;
 280 }
 281
 282 static void geth_disable(struct usb_function *f)
 283 {
 284         struct f_gether *geth = func_to_geth(f);
 285         struct usb_composite_dev *cdev = f->config->cdev;
 286
 287         DBG(cdev, "net deactivated\n");
 288         gether_disconnect(&geth->port);
 289 }
 290
 291 /*-------------------------------------------------------------------------*/
 292
 293 /* serial function driver setup/binding */
 294
 295 static int
 296 geth_bind(struct usb_configuration *c, struct usb_function *f)
 297 {
 298         struct usb_composite_dev *cdev = c->cdev;
 299         struct f_gether         *geth = func_to_geth(f);
 300         struct usb_string       *us;
 301         int                     status;
 302         struct usb_ep           *ep;
 303
 304 #ifndef USB_FSUBSET_INCLUDED
 305         struct f_gether_opts    *gether_opts;
 306
 307         gether_opts = container_of(f->fi, struct f_gether_opts, func_inst);
 308
 309         /*
 310          * in drivers/usb/gadget/configfs.c:configfs_composite_bind()
 311          * configurations are bound in sequence with list_for_each_entry,
 312          * in each configuration its functions are bound in sequence
 313          * with list_for_each_entry, so we assume no race condition
 314          * with regard to gether_opts->bound access
 315          */
 316         if (!gether_opts->bound) {
 317                 mutex_lock(&gether_opts->lock);
 318                 gether_set_gadget(gether_opts->net, cdev->gadget);
 319                 status = gether_register_netdev(gether_opts->net);
 320                 mutex_unlock(&gether_opts->lock);
 321                 if (status)
 322                         return status;
 323                 gether_opts->bound = true;
 324         }
 325 #endif
 326         us = usb_gstrings_attach(cdev, geth_strings,
 327                                  ARRAY_SIZE(geth_string_defs));
 328         if (IS_ERR(us))
 329                 return PTR_ERR(us);
 330
 331         subset_data_intf.iInterface = us[0].id;
 332         ether_desc.iMACAddress = us[1].id;
 333
 334         /* allocate instance-specific interface IDs */
 335         status = usb_interface_id(c, f);
 336         if (status < 0)
 337                 goto fail;
 338         subset_data_intf.bInterfaceNumber = status;
 339
 340         status = -ENODEV;
 341
 342         /* allocate instance-specific endpoints */
 343         ep = usb_ep_autoconfig(cdev->gadget, &fs_subset_in_desc);
 344         if (!ep)
 345                 goto fail;
 346         geth->port.in_ep = ep;
 347         ep->driver_data = cdev; /* claim */
 348
 349         ep = usb_ep_autoconfig(cdev->gadget, &fs_subset_out_desc);
 350         if (!ep)
 351                 goto fail;
 352         geth->port.out_ep = ep;
 353         ep->driver_data = cdev; /* claim */
 354
 355         /* support all relevant hardware speeds... we expect that when
 356          * hardware is dual speed, all bulk-capable endpoints work at
 357          * both speeds
 358          */
 359         hs_subset_in_desc.bEndpointAddress = fs_subset_in_desc.bEndpointAddress;
 360         hs_subset_out_desc.bEndpointAddress =
 361                 fs_subset_out_desc.bEndpointAddress;
 362
 363         ss_subset_in_desc.bEndpointAddress = fs_subset_in_desc.bEndpointAddress;
 364         ss_subset_out_desc.bEndpointAddress =
 365                 fs_subset_out_desc.bEndpointAddress;
 366
 367         status = usb_assign_descriptors(f, fs_eth_function, hs_eth_function,
 368                         ss_eth_function);
 369         if (status)
 370                 goto fail;
 371
 372         /* NOTE:  all that is done without knowing or caring about
 373          * the network link ... which is unavailable to this code
 374          * until we're activated via set_alt().
 375          */
 376
 377         DBG(cdev, "CDC Subset: %s speed IN/%s OUT/%s\n",
 378                         gadget_is_superspeed(c->cdev->gadget) ? "super" :
 379                         gadget_is_dualspeed(c->cdev->gadget) ? "dual" : "full",
 380                         geth->port.in_ep->name, geth->port.out_ep->name);
 381         return 0;
 382
 383 fail:
 384         usb_free_all_descriptors(f);
 385         /* we might as well release our claims on endpoints */
 386         if (geth->port.out_ep)
 387                 geth->port.out_ep->driver_data = NULL;
 388         if (geth->port.in_ep)
 389                 geth->port.in_ep->driver_data = NULL;
 390
 391         ERROR(cdev, "%s: can't bind, err %d\n", f->name, status);
 392
 393         return status;
 394 }
 395
 396 #ifdef USB_FSUBSET_INCLUDED
 397
 398 static void
 399 geth_old_unbind(struct usb_configuration *c, struct usb_function *f)
 400 {
 401         geth_string_defs[0].id = 0;
 402         usb_free_all_descriptors(f);
 403         kfree(func_to_geth(f));
 404 }
 405
 406 /**
 407  * geth_bind_config - add CDC Subset network link to a configuration
 408  * @c: the configuration to support the network link
 409  * @ethaddr: a buffer in which the ethernet address of the host side
 410  *      side of the link was recorded
 411  * @dev: eth_dev structure
 412  * Context: single threaded during gadget setup
 413  *
 414  * Returns zero on success, else negative errno.
 415  *
 416  * Caller must have called @gether_setup().  Caller is also responsible
 417  * for calling @gether_cleanup() before module unload.
 418  */
 419 int geth_bind_config(struct usb_configuration *c, u8 ethaddr[ETH_ALEN],
 420                 struct eth_dev *dev)
 421 {
 422         struct f_gether *geth;
 423         int             status;
 424
 425         /* allocate and initialize one new instance */
 426         geth = kzalloc(sizeof *geth, GFP_KERNEL);
 427         if (!geth)
 428                 return -ENOMEM;
 429
 430         /* export host's Ethernet address in CDC format */
 431         snprintf(geth->ethaddr, sizeof geth->ethaddr, "%pm", ethaddr);
 432         geth_string_defs[1].s = geth->ethaddr;
 433
 434         geth->port.ioport = dev;
 435         geth->port.cdc_filter = DEFAULT_FILTER;
 436
 437         geth->port.func.name = "cdc_subset";
 438         geth->port.func.bind = geth_bind;
 439         geth->port.func.unbind = geth_old_unbind;
 440         geth->port.func.set_alt = geth_set_alt;
 441         geth->port.func.disable = geth_disable;
 442
 443         status = usb_add_function(c, &geth->port.func);
 444         if (status)
 445                 kfree(geth);
 446         return status;
 447 }
 448
 449 #else
 450
 451 static inline struct f_gether_opts *to_f_gether_opts(struct config_item *item)
 452 {
 453         return container_of(to_config_group(item), struct f_gether_opts,
 454                             func_inst.group);
 455 }
 456
 457 /* f_gether_item_ops */
 458 USB_ETHERNET_CONFIGFS_ITEM(gether);
 459
 460 /* f_gether_opts_dev_addr */
 461 USB_ETHERNET_CONFIGFS_ITEM_ATTR_DEV_ADDR(gether);
 462
 463 /* f_gether_opts_host_addr */
 464 USB_ETHERNET_CONFIGFS_ITEM_ATTR_HOST_ADDR(gether);
 465
 466 /* f_gether_opts_qmult */
 467 USB_ETHERNET_CONFIGFS_ITEM_ATTR_QMULT(gether);
 468
 469 /* f_gether_opts_ifname */
 470 USB_ETHERNET_CONFIGFS_ITEM_ATTR_IFNAME(gether);
 471
 472 static struct configfs_attribute *gether_attrs[] = {
 473         &f_gether_opts_dev_addr.attr,
 474         &f_gether_opts_host_addr.attr,
 475         &f_gether_opts_qmult.attr,
 476         &f_gether_opts_ifname.attr,
 477         NULL,
 478 };
 479
 480 static struct config_item_type gether_func_type = {
 481         .ct_item_ops    = &gether_item_ops,
 482         .ct_attrs       = gether_attrs,
 483         .ct_owner       = THIS_MODULE,
 484 };
 485
 486 static void geth_free_inst(struct usb_function_instance *f)
 487 {
 488         struct f_gether_opts *opts;
 489
 490         opts = container_of(f, struct f_gether_opts, func_inst);
 491         if (opts->bound)
 492                 gether_cleanup(netdev_priv(opts->net));
 493         else
 494                 free_netdev(opts->net);
 495         kfree(opts);
 496 }
 497
 498 static struct usb_function_instance *geth_alloc_inst(void)
 499 {
 500         struct f_gether_opts *opts;
 501
 502         opts = kzalloc(sizeof(*opts), GFP_KERNEL);
 503         if (!opts)
 504                 return ERR_PTR(-ENOMEM);
 505         mutex_init(&opts->lock);
 506         opts->func_inst.free_func_inst = geth_free_inst;
 507         opts->net = gether_setup_default();
 508         if (IS_ERR(opts->net)) {
 509                 struct net_device *net = opts->net;
 510                 kfree(opts);
 511                 return ERR_CAST(net);
 512         }
 513
 514         config_group_init_type_name(&opts->func_inst.group, "",
 515                                     &gether_func_type);
 516
 517         return &opts->func_inst;
 518 }
 519
 520 static void geth_free(struct usb_function *f)
 521 {
 522         struct f_gether *eth;
 523
 524         eth = func_to_geth(f);
 525         kfree(eth);
 526 }
 527
 528 static void geth_unbind(struct usb_configuration *c, struct usb_function *f)
 529 {
 530         geth_string_defs[0].id = 0;
 531         usb_free_all_descriptors(f);
 532 }
 533
 534 static struct usb_function *geth_alloc(struct usb_function_instance *fi)
 535 {
 536         struct f_gether *geth;
 537         struct f_gether_opts *opts;
 538         int status;
 539
 540         /* allocate and initialize one new instance */
 541         geth = kzalloc(sizeof(*geth), GFP_KERNEL);
 542         if (!geth)
 543                 return ERR_PTR(-ENOMEM);
 544
 545         opts = container_of(fi, struct f_gether_opts, func_inst);
 546
 547         mutex_lock(&opts->lock);
 548         opts->refcnt++;
 549         /* export host's Ethernet address in CDC format */
 550         status = gether_get_host_addr_cdc(opts->net, geth->ethaddr,
 551                                           sizeof(geth->ethaddr));
 552         if (status < 12) {
 553                 kfree(geth);
 554                 mutex_unlock(&opts->lock);
 555                 return ERR_PTR(-EINVAL);
 556         }
 557         geth_string_defs[1].s = geth->ethaddr;
 558
 559         geth->port.ioport = netdev_priv(opts->net);
 560         mutex_unlock(&opts->lock);
 561         geth->port.cdc_filter = DEFAULT_FILTER;
 562
 563         geth->port.func.name = "cdc_subset";
 564         geth->port.func.bind = geth_bind;
 565         geth->port.func.unbind = geth_unbind;
 566         geth->port.func.set_alt = geth_set_alt;
 567         geth->port.func.disable = geth_disable;
 568         geth->port.func.free_func = geth_free;
 569
 570         return &geth->port.func;
 571 }
 572
 573 DECLARE_USB_FUNCTION_INIT(geth, geth_alloc_inst, geth_alloc);
 574 MODULE_LICENSE("GPL");
 575 MODULE_AUTHOR("David Brownell");
 576
 577 #endif