drivers/usb/gadget/function/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->enabled) {
 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 PTR_ERR_OR_ZERO(net);
 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         struct f_gether_opts    *gether_opts;
 305
 306         gether_opts = container_of(f->fi, struct f_gether_opts, func_inst);
 307
 308         /*
 309          * in drivers/usb/gadget/configfs.c:configfs_composite_bind()
 310          * configurations are bound in sequence with list_for_each_entry,
 311          * in each configuration its functions are bound in sequence
 312          * with list_for_each_entry, so we assume no race condition
 313          * with regard to gether_opts->bound access
 314          */
 315         if (!gether_opts->bound) {
 316                 mutex_lock(&gether_opts->lock);
 317                 gether_set_gadget(gether_opts->net, cdev->gadget);
 318                 status = gether_register_netdev(gether_opts->net);
 319                 mutex_unlock(&gether_opts->lock);
 320                 if (status)
 321                         return status;
 322                 gether_opts->bound = true;
 323         }
 324
 325         us = usb_gstrings_attach(cdev, geth_strings,
 326                                  ARRAY_SIZE(geth_string_defs));
 327         if (IS_ERR(us))
 328                 return PTR_ERR(us);
 329
 330         subset_data_intf.iInterface = us[0].id;
 331         ether_desc.iMACAddress = us[1].id;
 332
 333         /* allocate instance-specific interface IDs */
 334         status = usb_interface_id(c, f);
 335         if (status < 0)
 336                 goto fail;
 337         subset_data_intf.bInterfaceNumber = status;
 338
 339         status = -ENODEV;
 340
 341         /* allocate instance-specific endpoints */
 342         ep = usb_ep_autoconfig(cdev->gadget, &fs_subset_in_desc);
 343         if (!ep)
 344                 goto fail;
 345         geth->port.in_ep = ep;
 346
 347         ep = usb_ep_autoconfig(cdev->gadget, &fs_subset_out_desc);
 348         if (!ep)
 349                 goto fail;
 350         geth->port.out_ep = ep;
 351
 352         /* support all relevant hardware speeds... we expect that when
 353          * hardware is dual speed, all bulk-capable endpoints work at
 354          * both speeds
 355          */
 356         hs_subset_in_desc.bEndpointAddress = fs_subset_in_desc.bEndpointAddress;
 357         hs_subset_out_desc.bEndpointAddress =
 358                 fs_subset_out_desc.bEndpointAddress;
 359
 360         ss_subset_in_desc.bEndpointAddress = fs_subset_in_desc.bEndpointAddress;
 361         ss_subset_out_desc.bEndpointAddress =
 362                 fs_subset_out_desc.bEndpointAddress;
 363
 364         status = usb_assign_descriptors(f, fs_eth_function, hs_eth_function,
 365                         ss_eth_function);
 366         if (status)
 367                 goto fail;
 368
 369         /* NOTE:  all that is done without knowing or caring about
 370          * the network link ... which is unavailable to this code
 371          * until we're activated via set_alt().
 372          */
 373
 374         DBG(cdev, "CDC Subset: %s speed IN/%s OUT/%s\n",
 375                         gadget_is_superspeed(c->cdev->gadget) ? "super" :
 376                         gadget_is_dualspeed(c->cdev->gadget) ? "dual" : "full",
 377                         geth->port.in_ep->name, geth->port.out_ep->name);
 378         return 0;
 379
 380 fail:
 381         ERROR(cdev, "%s: can't bind, err %d\n", f->name, status);
 382
 383         return status;
 384 }
 385
 386 static inline struct f_gether_opts *to_f_gether_opts(struct config_item *item)
 387 {
 388         return container_of(to_config_group(item), struct f_gether_opts,
 389                             func_inst.group);
 390 }
 391
 392 /* f_gether_item_ops */
 393 USB_ETHERNET_CONFIGFS_ITEM(gether);
 394
 395 /* f_gether_opts_dev_addr */
 396 USB_ETHERNET_CONFIGFS_ITEM_ATTR_DEV_ADDR(gether);
 397
 398 /* f_gether_opts_host_addr */
 399 USB_ETHERNET_CONFIGFS_ITEM_ATTR_HOST_ADDR(gether);
 400
 401 /* f_gether_opts_qmult */
 402 USB_ETHERNET_CONFIGFS_ITEM_ATTR_QMULT(gether);
 403
 404 /* f_gether_opts_ifname */
 405 USB_ETHERNET_CONFIGFS_ITEM_ATTR_IFNAME(gether);
 406
 407 static struct configfs_attribute *gether_attrs[] = {
 408         &gether_opts_attr_dev_addr,
 409         &gether_opts_attr_host_addr,
 410         &gether_opts_attr_qmult,
 411         &gether_opts_attr_ifname,
 412         NULL,
 413 };
 414
 415 static struct config_item_type gether_func_type = {
 416         .ct_item_ops    = &gether_item_ops,
 417         .ct_attrs       = gether_attrs,
 418         .ct_owner       = THIS_MODULE,
 419 };
 420
 421 static void geth_free_inst(struct usb_function_instance *f)
 422 {
 423         struct f_gether_opts *opts;
 424
 425         opts = container_of(f, struct f_gether_opts, func_inst);
 426         if (opts->bound)
 427                 gether_cleanup(netdev_priv(opts->net));
 428         else
 429                 free_netdev(opts->net);
 430         kfree(opts);
 431 }
 432
 433 static struct usb_function_instance *geth_alloc_inst(void)
 434 {
 435         struct f_gether_opts *opts;
 436
 437         opts = kzalloc(sizeof(*opts), GFP_KERNEL);
 438         if (!opts)
 439                 return ERR_PTR(-ENOMEM);
 440         mutex_init(&opts->lock);
 441         opts->func_inst.free_func_inst = geth_free_inst;
 442         opts->net = gether_setup_default();
 443         if (IS_ERR(opts->net)) {
 444                 struct net_device *net = opts->net;
 445                 kfree(opts);
 446                 return ERR_CAST(net);
 447         }
 448
 449         config_group_init_type_name(&opts->func_inst.group, "",
 450                                     &gether_func_type);
 451
 452         return &opts->func_inst;
 453 }
 454
 455 static void geth_free(struct usb_function *f)
 456 {
 457         struct f_gether *eth;
 458
 459         eth = func_to_geth(f);
 460         kfree(eth);
 461 }
 462
 463 static void geth_unbind(struct usb_configuration *c, struct usb_function *f)
 464 {
 465         geth_string_defs[0].id = 0;
 466         usb_free_all_descriptors(f);
 467 }
 468
 469 static struct usb_function *geth_alloc(struct usb_function_instance *fi)
 470 {
 471         struct f_gether *geth;
 472         struct f_gether_opts *opts;
 473         int status;
 474
 475         /* allocate and initialize one new instance */
 476         geth = kzalloc(sizeof(*geth), GFP_KERNEL);
 477         if (!geth)
 478                 return ERR_PTR(-ENOMEM);
 479
 480         opts = container_of(fi, struct f_gether_opts, func_inst);
 481
 482         mutex_lock(&opts->lock);
 483         opts->refcnt++;
 484         /* export host's Ethernet address in CDC format */
 485         status = gether_get_host_addr_cdc(opts->net, geth->ethaddr,
 486                                           sizeof(geth->ethaddr));
 487         if (status < 12) {
 488                 kfree(geth);
 489                 mutex_unlock(&opts->lock);
 490                 return ERR_PTR(-EINVAL);
 491         }
 492         geth_string_defs[1].s = geth->ethaddr;
 493
 494         geth->port.ioport = netdev_priv(opts->net);
 495         mutex_unlock(&opts->lock);
 496         geth->port.cdc_filter = DEFAULT_FILTER;
 497
 498         geth->port.func.name = "cdc_subset";
 499         geth->port.func.bind = geth_bind;
 500         geth->port.func.unbind = geth_unbind;
 501         geth->port.func.set_alt = geth_set_alt;
 502         geth->port.func.disable = geth_disable;
 503         geth->port.func.free_func = geth_free;
 504
 505         return &geth->port.func;
 506 }
 507
 508 DECLARE_USB_FUNCTION_INIT(geth, geth_alloc_inst, geth_alloc);
 509 MODULE_LICENSE("GPL");
 510 MODULE_AUTHOR("David Brownell");