Linux usb gadget框架概述
作者：互联网
大大小小开发了四个与gadget相关的驱动，字符驱动、g_multi、g_ether、g_zero，在这里把自己对gadget的开发中自己的感悟记录之。
想要了解gadget，必须了解其框架，知道composite、gadget、udc三者之间的联系，知道usb描述符的作用。
一个usb device有一个设备描述符。
有一个或者多个配置描述符
一个配置描述符有一个或者多个接口（在gadget端，接口正式命名是usb_func）。
一个接口有0个或者多个端点。
编写gadget的关键是在于了解udc、gadget、composite三者之间的联系和架构层次，在实际应用中gadget是不需要我们去编写的，需要我们自己去编写的是composite层，以及地对udc层的修改，下面开始详细介绍着三者。
1、composite英文意思是复合的意思，估计是编写usb gadget层设备驱动都整合到一起，通过统一的函数usb_composite_register注册。功能各异，杂七杂八，所以称为复合层吧。
在该层，我们需要注意的相关结构体和函数有如下：
struct usb_composite_dev { //作为composite复合设备，所有composite设备都必须实现该设备。
struct usb_gadget *gadget; //设备和gadget交互，gadget和udc交互。
struct usb_request *req; //每个设备自带一个usb请求，所有的数据交互都是通过该请求发送的。
struct usb_configuration *config; 一个设备有一个或者多个配置。
/* private: */
/* internals */
unsigned int suspended:1;
struct usb_device_descriptor desc; //设备描述符，唯一
struct list_head configs; //配置
struct list_head gstrings; //字符描述
struct usb_composite_driver *driver; //设备绑定的驱动
u8 next_string_id;
char *def_manufacturer; //默认制造商
/* the gadget driver won't enable the data pullup
* while the deactivation count is nonzero.
*/
unsigned deactivations;
/* the composite driver won't complete the control transfer's
* data/status stages till delayed_status is zero.
*/
int delayed_status;
/* protects deactivations and delayed_status counts*/
spinlock_t lock;
};307 struct usb_composite_driver { //所有compesite驱动必须填充该结构体。
308 const char *name;
309 const struct usb_device_descriptor *dev; //必须实现
310 struct usb_gadget_strings **strings;
311 enum usb_device_speed max_speed;
312 unsigned needs_serial:1;
313
314 int (*bind)(struct usb_composite_dev *cdev); //必须实现的
315 int (*unbind)(struct usb_composite_dev *); //必须实现
316
317 void (*disconnect)(struct usb_composite_dev *);
318
319 /* global suspend hooks */
320 void (*suspend)(struct usb_composite_dev *);
321 void (*resume)(struct usb_composite_dev *);
322 struct usb_gadget_driver gadget_driver; //这个地方的驱动由composite提供，所有和composite相关的驱动都会默认分配该驱动。该驱动是
323 }; 852 struct usb_gadget_driver { //该驱动是usbcore和composite之间交互必不可少的一环，两者之间的联系主要靠他来维持，内核已经提供好了，不需要我们去实现。
853 char *function;
854 enum usb_device_speed max_speed;
855 int (*bind)(struct usb_gadget *gadget,
856 struct usb_gadget_driver *driver);
857 void (*unbind)(struct usb_gadget *);
858 int (*setup)(struct usb_gadget *, //枚举过程中必不可少的函数。不需要驱动去实现。
859 const struct usb_ctrlrequest *);
860 void (*disconnect)(struct usb_gadget *);
861 void (*suspend)(struct usb_gadget *);
862 void (*resume)(struct usb_gadget *);
863
864 /* FIXME support safe rmmod */
865 struct device_driver driver;
866 };
1772 static const struct usb_gadget_driver composite_driver_template = { //所有的composite设备都会在注册gadet驱动的时候采用该实例填充。
//笔者认为这么做的原因是gadget驱动永远只有一个，composite可以随便实现。体现分层的思想。
1773 .bind = composite_bind,
1774 .unbind = composite_unbind,
1775
1776 .setup = composite_setup,
1777 .disconnect = composite_disconnect,
1778
1779 .suspend = composite_suspend,
1780 .resume = composite_resume,
1781
1782 .driver = {
1783 .owner = THIS_MODULE,
1784 },
1785 };
下面首先介绍composite驱动的注册过程，讲完后介绍驱动的编写过程。
以zero.c为例：
static int __init init(void) { return usb_composite_register(&zero_driver); } usb_composite_register(&zero_driver); 1========》 driver->gadget_driver = composite_driver_template; //此过程并未涉及到对compoite设备的注册的操作， //而是将composite驱动中注册的相关信息填充到gadget中，利用gadget去和udc打交道 ---->return usb_gadget_probe_driver(gadget_driver); 该函数首先判定bind setup等函数是否实现了。不需要我们去实现。 ----> list_for_each_entry(udc, &udc_list, list) //查找注册在内核中的udc实例，找到了进行下一步操作，没找到退出。驱动注册失败。 ----> ret = udc_bind_to_driver(udc, driver); //将udc和gadget驱动绑定在一起。 2======》 udc_bind_to_driver(udc, driver); ---->404 ret = driver->bind(udc->gadget, driver);//最关键的莫过于该函数了，最初笔者分析的时候，以为是composite的bind函数，后来才弄清楚是gadget层 //的bind函数composite_bind ，将在后面介绍。 -----> ret = usb_gadget_udc_start(udc->gadget, driver); //此处可以理解为一切就绪，udc相关设置已经写入寄存器。 -----> ret = usb_gadget_connect(udc->gadget); //插入host usb口，检查D+电平的变化。也就是枚举过冲 3=====》 composite_bind //最重要的函数了。是理解gadget设计的关键1672 static int composite_bind(struct usb_gadget *gadget,//该函数zhu要是实现配置描述符接口等操作。 1673 struct usb_gadget_driver *gdriver) 1674 { 1675 struct usb_composite_dev *cdev; 1676 struct usb_composite_driver *composite = to_cdriver(gdriver); 1677 int status = -ENOMEM; 1678 1679 cdev = kzalloc(sizeof *cdev, GFP_KERNEL); 1680 if (!cdev) 1681 return status; 1682 1683 spin_lock_init(&cdev->lock); 1684 cdev->gadget = gadget; 1685 set_gadget_data(gadget, cdev); 1686 INIT_LIST_HEAD(&cdev->configs); 1687 INIT_LIST_HEAD(&cdev->gstrings); 1688 1689 status = composite_dev_prepare(composite, cdev); 1690 if (status) 1691 goto fail; 1692 1693 /* composite gadget needs to assign strings for whole device (like 1694 ┊* serial number), register function drivers, potentially update 1695 ┊* power state and consumption, etc 1696 ┊*/ 1697 /*此处才是开始调用驱动的bind函数*/ 1698 status = composite->bind(cdev); 1699 if (status < 0) 1700 goto fail; 1701 1702 update_unchanged_dev_desc(&cdev->desc, composite->dev); 1703 1704 /* has userspace failed to provide a serial number? */ 1705 if (composite->needs_serial && !cdev->desc.iSerialNumber) 1706 WARNING(cdev, "userspace failed to provide iSerialNumber\n"); 1707 1708 INFO(cdev, "%s ready\n", composite->name); 1709 return 0; 1710 1711 fail: 1712 __composite_unbind(gadget, false); 1713 return status; } 1====》 composite_bind ---->1676 struct usb_composite_driver *composite = to_cdriver(gdriver); //这个函数就是将gadet转换为composite的关键。在gadget驱动注册时联系在一起。 //return container_of(gdrv, struct usb_composite_driver, gadget_driver); ---->cdev = kzalloc(sizeof *cdev, GFP_KERNEL); //实现cdev设备。 ---->set_gadget_data(gadget, cdev); //填充私有数据，以便内核中可以通过gadget获取cdev. ---->INIT_LIST_HEAD(&cdev->configs); //初始化配置描述链表，在开头本人介绍过，一个设备有一个或者多种配置。 ---->1689 status = composite_dev_prepare(composite, cdev); //这个函数十分重要，包括usb_request、complete（回调函数实现）、设备和驱动的绑定等） ---->1698 status = composite->bind(cdev) //此处才是开始调用驱动的bind函数,后面会详细介绍该函数。 ----> INFO(cdev, "%s ready\n", composite->name); //至此，composite设备创建成功。1610 int composite_dev_prepare(struct usb_composite_driver *composite, //该函数主要是实现了至关重要的usb_request，针对端点0，即控制端点 1611 struct usb_composite_dev *cdev) 1612 { 1613 struct usb_gadget *gadget = cdev->gadget; 1614 int ret = -ENOMEM; 1615 1616 /* preallocate control response and buffer */ 1617 cdev->req = usb_ep_alloc_request(gadget->ep0, GFP_KERNEL); //申请控制端点usb请求 1618 if (!cdev->req) 1619 return -ENOMEM; 1620 1621 cdev->req->buf = kmalloc(USB_COMP_EP0_BUFSIZ, GFP_KERNEL); //请求发送内容将保持在此 1622 if (!cdev->req->buf) 1623 goto fail; 1624 1625 ret = device_create_file(&gadget->dev, &dev_attr_suspended);//创建设备文件，位于/sys/class/dev目录下 1626 if (ret) 1627 goto fail_dev; 1628 1629 cdev->req->complete = composite_setup_complete; //回调函数。 1630 gadget->ep0->driver_data = cdev; //通过端点即可获取设备。 1631 1632 cdev->driver = composite; //将composite设备和驱动绑定在一起，所以usb gadget端是没有枚举过程的，驱动直接注册成功，创建设备。 1633 1634 /* 1635 ┊* As per USB compliance update, a device that is actively drawing 1636 ┊* more than 100mA from USB must report itself as bus-powered in 1637 ┊* the GetStatus(DEVICE) call. 1638 ┊*/ 1639 if (CONFIG_USB_GADGET_VBUS_DRAW <= USB_SELF_POWER_VBUS_MAX_DRAW) 1640 usb_gadget_set_selfpowered(gadget); 1641 1642 /* interface and string IDs start at zero via kzalloc. 1643 ┊* we force endpoints to start unassigned; few controller 1644 ┊* drivers will zero ep->driver_data. 1645 ┊*/ 1646 usb_ep_autoconfig_reset(gadget); // 1647 return 0; 1648 fail_dev 1649 kfree(cdev->req->buf); 1650 fail: /* 此处知识初始化了usb配置链表，并未实例化接口和端点，所以将端点driver_data又重设为空，批量输入和输出点号为0； 1642 /* interface and string IDs start at zero via kzalloc. 1643 ┊* we force endpoints to start unassigned; few controller 1644 ┊* drivers will zero ep->driver_data. 1645 ┊*/ 1646 usb_ep_autoconfig_reset(gadget); */ 1651 usb_ep_free_request(gadget->ep0, cdev->req); 1652 cdev->req = NULL; 1653 return ret; 1654 }
下面即将进行到至关重要的一环，调用composite驱动的bind函数。275 static int __init zero_bind(struct usb_composite_dev *cdev) //里面是实现composite设备的关键，设计到strings，配置描述符，接口（function）、端点的实例化。 /276 { 277 struct f_ss_opts *ss_opts; 278 struct f_lb_opts *lb_opts; 279 int status; 280 281 /* Allocate string descriptor numbers ... note that string 282 ┊* contents can be overridden by the composite_dev glue. 283 ┊*/ 284 status = usb_string_ids_tab(cdev, strings_dev); 285 if (status < 0) 286 return status; 287 288 device_desc.iManufacturer = strings_dev[USB_GADGET_MANUFACTURER_IDX].id;//制造商 289 device_desc.iProduct = strings_dev[USB_GADGET_PRODUCT_IDX].id;//产品Id 290 device_desc.iSerialNumber = strings_dev[USB_GADGET_SERIAL_IDX].id;//设备序列号功能索引，个人认为是针对多function设备而言的。 291 292 setup_timer(&autoresume_timer, zero_autoresume, (unsigned long) cdev); 293 294 func_inst_ss = usb_get_function_instance("SourceSink"); //获取function,此处的实现十分巧妙，通过usb_function_register实现。 295 if (IS_ERR(func_inst_ss)) 296 return PTR_ERR(func_inst_ss); 297 298 ss_opts = container_of(func_inst_ss, struct f_ss_opts, func_inst); 299 ss_opts->pattern = gzero_options.pattern; 300 ss_opts->isoc_interval = gzero_options.isoc_interval; 301 ss_opts->isoc_maxpacket = gzero_options.isoc_maxpacket; 302 ss_opts->isoc_mult = gzero_options.isoc_mult; 303 ss_opts->isoc_maxburst = gzero_options.isoc_maxburst; 304 ss_opts->bulk_buflen = gzero_options.bulk_buflen; //每次传送的buf大小 305 306 func_ss = usb_get_function(func_inst_ss); //获取source_link实例，同样通过usb_function_register注册获取。 307 if (IS_ERR(func_ss)) { 308 status = PTR_ERR(func_ss); 309 goto err_put_func_inst_ss; 310 } 311 312 func_inst_lb = usb_get_function_instance("Loopback"); 313 if (IS_ERR(func_inst_lb)) { 314 status = PTR_ERR(func_inst_lb); 315 goto err_put_func_ss; 316 } 317 318 lb_opts = container_of(func_inst_lb, struct f_lb_opts, func_inst); 319 lb_opts->bulk_buflen = gzero_options.bulk_buflen; //在usb_function_registe注册时就已经分配了。 320 lb_opts->qlen = gzero_options.qlen; 321 322 func_lb = usb_get_function(func_inst_lb); 323 if (IS_ERR(func_lb)) { 324 status = PTR_ERR(func_lb); 325 goto err_put_func_inst_lb; 326 } 327 328 sourcesink_driver.iConfiguration = strings_dev[USB_GZERO_SS_DESC].id;//设置配置描述符索引 329 loopback_driver.iConfiguration = strings_dev[USB_GZERO_LB_DESC].id; 330 331 /* support autoresume for remote wakeup testing */ 332 sourcesink_driver.bmAttributes &= ~USB_CONFIG_ATT_WAKEUP; 333 loopback_driver.bmAttributes &= ~USB_CONFIG_ATT_WAKEUP; 334 sourcesink_driver.descriptors = NULL; 335 loopback_driver.descriptors = NULL; 336 if (autoresume) { 337 sourcesink_driver.bmAttributes |= USB_CONFIG_ATT_WAKEUP; 338 loopback_driver.bmAttributes |= USB_CONFIG_ATT_WAKEUP; 339 autoresume_step_ms = autoresume * 1000; 340 } 341 342 /* support OTG systems */ 343 if (gadget_is_otg(cdev->gadget)) { 344 sourcesink_driver.descriptors = otg_desc; 345 sourcesink_driver.bmAttributes |= USB_CONFIG_ATT_WAKEUP; 346 loopback_driver.descriptors = otg_desc; 347 loopback_driver.bmAttributes |= USB_CONFIG_ATT_WAKEUP; 348 } 349 350 /* Register primary, then secondary configuration. Note that 351 ┊* SH3 only allows one config... 352 ┊*/ 353 if (loopdefault) {//若只支持loopback即回环模式。 354 usb_add_config_only(cdev, &loopback_driver);//则loopback配置先注册 355 usb_add_config_only(cdev, &sourcesink_driver);//后注册 356 } else { 357 usb_add_config_only(cdev, &sourcesink_driver);//同上 358 usb_add_config_only(cdev, &loopback_driver); 359 } 360 status = usb_add_function(&sourcesink_driver, func_ss);//将功能即接口绑定到配置描述符，此处还有一次bind操作，隐藏的极深。 361 if (status) 362 goto err_conf_flb; 363 364 usb_ep_autoconfig_reset(cdev->gadget);//重新设置ep 365 status = usb_add_function(&loopback_driver, func_lb); 366 if (status) 367 goto err_conf_flb; 368 369 usb_ep_autoconfig_reset(cdev->gadget); 370 usb_composite_overwrite_options(cdev, &coverwrite);//支持传参。修改iverdor iproduct等。 371 372 INFO(cdev, "%s, version: " DRIVER_VERSION "\n", longname); 373 374 return 0; 375 376 err_conf_flb: 377 usb_put_function(func_lb); 378 func_lb = NULL; 379 err_put_func_inst_lb: 380 usb_put_function_instance(func_inst_lb); 381 func_inst_lb = NULL; 382 err_put_func_ss: 383 usb_put_function(func_ss); 384 func_ss = NULL; 385 err_put_func_inst_ss: 386 usb_put_function_instance(func_inst_ss); 387 func_inst_ss = NULL; 388 return status; 389 }189 int usb_add_function(struct usb_configuration *config, //配置中实例化接口。 190 struct usb_function *function) 191 { 192 int value = -EINVAL; 193 194 DBG(config->cdev, "adding '%s'/%p to config '%s'/%p\n", 195 function->name, function, 196 config->label, config); 197 198 if (!function->set_alt || !function->disable)//接口是否设置了set_alt函数，该函数调用表示当前接口可用，其他接口不可用。 199 goto done; 200 201 function->config = config; 202 list_add_tail(&function->list, &config->functions); 203 204 /* REVISIT *require* function->bind? */ 205 if (function->bind) { 206 value = function->bind(config, function);//对于一个配置多个接口的cdev设备，再次对function进行bin操作。 207 if (value < 0) { 208 list_del(&function->list); 209 function->config = NULL; 210 } 211 } else 212 value = 0; 213 214 /* We allow configurations that don't work at both speeds. 215 ┊* If we run into a lowspeed Linux system, treat it the same 216 ┊* as full speed ... it's the function drivers that will need 217 ┊* to avoid bulk and ISO transfers. 218 ┊*/ 219 if (!config->fullspeed && function->fs_descriptors) 220 config->fullspeed = true; 221 if (!config->highspeed && function->hs_descriptors) 222 config->highspeed = true; 223 if (!config->superspeed && function->ss_descriptors) 224 config->superspeed = true; 225 226 done: 227 if (value) 228 DBG(config->cdev, "adding '%s'/%p --> %d\n", 229 function->name, function, value); 230 return value; 231 }以f_loopback.c中的bind为例。
175 static int loopback_bind(struct usb_configuration *c, struct usb_function *f) //将配置和功能绑定在一起 176 { 177 struct usb_composite_dev *cdev = c->cdev; 178 struct f_loopback *loop = func_to_loop(f); 179 int id; 180 int ret; 181 182 /* allocate interface ID(s) */ 183 id = usb_interface_id(c, f);//一般从0开始配置。分配接口id号 184 if (id < 0) 185 return id; 186 loopback_intf.bInterfaceNumber = id; 187 188 id = usb_string_id(cdev);//获取字符描述符索引 189 if (id < 0) 190 return id; 191 strings_loopback[0].id = id; 192 loopback_intf.iInterface = id; 193 194 /* allocate endpoints */ 195 196 loop->in_ep = usb_ep_autoconfig(cdev->gadget, &fs_loop_source_desc);//分配批量输入端点 197 if (!loop->in_ep) { 198 autoconf_fail: 199 ERROR(cdev, "%s: can't autoconfigure on %s\n", 200 f->name, cdev->gadget->name); 201 return -ENODEV; 202 } 203 loop->in_ep->driver_data = cdev; /* claim */ 204 205 loop->out_ep = usb_ep_autoconfig(cdev->gadget, &fs_loop_sink_desc);//分配批量输出端点 206 if (!loop->out_ep) 207 goto autoconf_fail; 208 loop->out_ep->driver_data = cdev; /* claim */ 209 210 /* support high speed hardware */ 211 hs_loop_source_desc.bEndpointAddress = 212 fs_loop_source_desc.bEndpointAddress; 213 hs_loop_sink_desc.bEndpointAddress = fs_loop_sink_desc.bEndpointAddress; 214 215 /* support super speed hardware */ 216 ss_loop_source_desc.bEndpointAddress = 217 fs_loop_source_desc.bEndpointAddress; 218 ss_loop_sink_desc.bEndpointAddress = fs_loop_sink_desc.bEndpointAddress; 219 220 ret = usb_assign_descriptors(f, fs_loopback_descs, hs_loopback_descs, //此处主要设设置usb速度。 221 ss_loopback_descs); 222 if (ret) 223 return ret; 224 225 DBG(cdev, "%s speed %s: IN/%s, OUT/%s\n", 226 ┊ (gadget_is_superspeed(c->cdev->gadget) ? "super" : 227 ┊ ┊(gadget_is_dualspeed(c->cdev->gadget) ? "dual" : "full")), 228 f->name, loop->in_ep->name, loop->out_ep->name); 229 return 0; 230 }至此gadget框架只驱动注册过程已经介绍完成。下面再来介绍下驱动的注册流程。
- 填充usb_composite_driver驱动实例，调用usb_composite_probe进行注。
- 移花接木，填充usb_composite驱动中gadget_driver,调用usb_gadget_probe_driver(gadget_driver);使得udc能够和composite设备联系起来。
- 调用udc_bind_to_driver，慢慢的将udc和composite绑定在一起。
- 调用driver->bind(udc->gadget, driver);实际上是调用composite_bind函数，该函数由内核实现。该函数主要是创建cdev设备，将真正的驱动和cdev绑定在一起。
- 此后再调用编写的驱动的bind函数。此时主要是讲cdev设备的配置和function进行填充。设备必须有配置，配置必须有接口。
- 针对多function的驱动，必须再次绑定bind函数，此次主要是设置接口id,实例化ep等。
- 前6步操作的完成，表示composite设备驱动已经注册成功了。成功了之后呢？那就涉及到对udc的操作了，udc进入请求连接状态，等待中断的响应。
- 中断响应也就是响应主设备发起的枚举操作，完成枚举过程，枚举响应主要是调用function->setup函数。枚举过程将在另外一篇文章中介绍。
标签：usb,composite,gadget,driver,cdev,Linux,struct 来源： https://blog.51cto.com/u_15169172/2710506