Several improvements to USB gadgets
Subsystems (2)
PATCH v2 2/7 USB: gadget: f_mass_storage: fsg_add() renamed to fsg_bind_config()
In reply to Michal NazarewiczMass Storage Function had a bit unique name for function used to add it to USB configuration. Renamed as to match naming convention of other functions.
--- drivers/usb/gadget/f_mass_storage.c | 13 ++++++++++--- drivers/usb/gadget/mass_storage.c | 2 +- drivers/usb/gadget/multi.c | 4 ++-- 3 files changed, 13 insertions(+), 6 deletions(-)
drivers/usb/gadget/f_mass_storage.c +10 -3
@@ -3023,9 +3023,9 @@ static struct usb_gadget_strings *fsg_strings_array[] = { NULL, }; -static int fsg_add (struct usb_composite_dev *cdev, -struct usb_configuration *c, -struct fsg_common *common) +static int fsg_bind_config (struct usb_composite_dev *cdev, +struct usb_configuration *c, +struct fsg_common *common) {struct fsg_dev *fsg;int rc;
@@ -3072,6 +3072,13 @@ error_free_fsg:return rc; } +static inline int __deprecated __maybe_unused +fsg_add (struct usb_composite_dev *cdev, +struct usb_configuration *c, +struct fsg_common *common) +{ +return fsg_bind_config (cdev, c, common); +}/************************* Module parameters *************************/
drivers/usb/gadget/mass_storage.c +1 -1
@@ -159,7 +159,7 @@ static int __init msg_do_config(struct usb_configuration *c)if (IS_ERR (retp))return PTR_ERR (retp); - ret =fsg_add (c->cdev, c, &common); + ret =fsg_bind_config (c->cdev, c, &common);fsg_common_put (&common);return ret; }
drivers/usb/gadget/multi.c +2 -2
@@ -172,7 +172,7 @@ static int __init rndis_do_config(struct usb_configuration *c)if (ret <0 )return ret; - ret =fsg_add (c->cdev, c, fsg_common); + ret =fsg_bind_config (c->cdev, c, fsg_common);if (ret <0 )return ret;
@@ -208,7 +208,7 @@ static int __init cdc_do_config(struct usb_configuration *c)if (ret <0 )return ret; - ret =fsg_add (c->cdev, c, fsg_common); + ret =fsg_bind_config (c->cdev, c, fsg_common);if (ret <0 )return ret;
Signature · 1 line
1.7.1
v2 cover Several improvements to USB gadgets
Hello everyone,
I'm resending my earlier patchsets with two changes.
First of all, there was a tiny coding style bug in one of the patches (reported by Sergei Shtylyov).
Second of all, David has shown some concerns about overcomplicating the g_multi driver by introducing several Kconfig options. I assumed he knows better and so excluded this particular patch from the set.
The other patch modifying the g_multi is however legitimate in my opinion as it clears the code and fixes some section mismatch warnings.
The whole patchset introduces several improvements to USB gadgets, functions, etc.:
Michal Nazarewicz (7):
USB: gadget: g_mass_storage: static data instead of dynamic
allocation
A micro optimisation preventing a kmalloc call() which would otherwise be always called at the very beginning for the same area size.
This was submitted previously but Greg did not included it in his quilt tree (unless I overlooked something) so I'll posting it again for completeness. Sorry if that creates confusion.
In my opinion this is worth including as it simplifies the code a bit and removes the call to kmalloc/kfree (hidden in fsg_common_init) which in my opinion is a good thing as well.
Note, that the next patch won't apply without this one -- conflict is trivial to solve though.
USB: gadget: f_mass_storage: fsg_add() renamed to fsg_bind_config()
USB: gadget: f_fs: functionfs_add() renamed to
functionfs_bind_config()
All other functions use foo_bind_config() to add function to USB configuration so changed the names for mass storage and FunctionFS as well.
The inconstancy apparent in multifunction gadgets stroke me for quite some time now. I was always reluctant to submit patch thinking that it would be just stupid name change but finally couldn't stand it. ;)
In case of mass storage the old (fsg_add()) function is still available but marked deprecated. In case of FFS the old (functionfs_add()) function has been removed.
USB: gadget: composite: usb_string_ids_*() functions added
USB: gadget: f_fs: use usb_string_ids_n()
usb_string_ids_n() and usb_string_ids_tab() functions added for batch sting IDs requests.
USB: gadget: g_multi: code clean up and refactoring
USB: gadget: g_multi: added documentation and INF files
g_multi clean up, fixes, etc. Also, the last patch includes a bit of documentation for g_multi and an INF file tested with Windows XP SP3. Hopefully, someone will find it useful.
Documentation/usb/gadget_multi.txt | 160 ++++++++++++++++++ Documentation/usb/gadget_multi_rndis.inf | 200 ++++++++++++++++++++++ Documentation/usb/gadget_multi_serial.inf | 44 +++++ drivers/usb/gadget/Kconfig | 1 + drivers/usb/gadget/composite.c | 67 +++++++- drivers/usb/gadget/f_fs.c | 36 ++--- drivers/usb/gadget/f_mass_storage.c | 13 +- drivers/usb/gadget/g_ffs.c | 2 +- drivers/usb/gadget/mass_storage.c | 13 +- drivers/usb/gadget/multi.c | 262 ++++++++++++++++------------- include/linux/usb/composite.h | 4 + include/linux/usb/functionfs.h | 6 +- 12 files changed, 656 insertions(+), 152 deletions(-) create mode 100644 Documentation/usb/gadget_multi.txt create mode 100644 Documentation/usb/gadget_multi_rndis.inf create mode 100644 Documentation/usb/gadget_multi_serial.inf
--
Best regards, _ _
| Humble Liege of Serenely Enlightened Majesty of o' \,=./ `o
| Computer Science, Micha흢 "mina86" Nazarewicz (o o)
+----[mina86*mina86.com]---[mina86*jabber.org]----ooO--(_)--Ooo--
PATCH v2 1/7 USB: gadget: g_mass_storage: static data instead of dynamic allocation
This patch changes msg_do_config() function so that it uses a static object for a fsg_common structure instead of dynamically allocated. This is a micro-optimisation.
--- drivers/usb/gadget/mass_storage.c | 13 +++++++------ 1 files changed, 7 insertions(+), 6 deletions(-)
drivers/usb/gadget/mass_storage.c +7 -6
@@ -143,7 +143,7 @@ static int msg_thread_exits(struct fsg_common *common)static int __init msg_do_config (struct usb_configuration *c) { -struct fsg_common *common; +static struct fsg_common common, *retp;struct fsg_config config;int ret;
@@ -154,12 +154,13 @@ static int __init msg_do_config(struct usb_configuration *c)fsg_config_from_params (&config, &mod_data); config.thread_exits = msg_thread_exits; - common =fsg_common_init (0 , c->cdev, &config); -if (IS_ERR (common)) -return PTR_ERR (common); - ret =fsg_add (c->cdev, c, common); -fsg_common_put (common); + retp =fsg_common_init (&common, c->cdev, &config); +if (IS_ERR (retp)) +return PTR_ERR (retp); + + ret =fsg_add (c->cdev, c, &common); +fsg_common_put (&common);return ret; }
Signature · 1 line
1.7.1
PATCH v2 7/7 USB: gadget: g_multi: added documentation and INF files
In reply to Michal NazarewiczA short documentation of the g_multi driver along with INF files for Windows XP SP3 are provided.
--- Documentation/usb/gadget_multi.txt | 160 +++++++++++++++++++++++ Documentation/usb/gadget_multi_rndis.inf | 200 +++++++++++++++++++++++++++++ Documentation/usb/gadget_multi_serial.inf | 44 +++++++ 3 files changed, 404 insertions(+), 0 deletions(-) create mode 100644 Documentation/usb/gadget_multi.txt create mode 100644 Documentation/usb/gadget_multi_rndis.inf create mode 100644 Documentation/usb/gadget_multi_serial.inf
Documentation/usb/gadget_multi.txt new file +160 -0
@@ -0,0 +1,160 @@ + -*- org -*- + +* Overview + +The Multifunction Composite Gadget (or g_multi) is a customisable +composite gadget that makes extensive use of the composite framework +to provide a... multifunction gadget. + +In it's standard configuration it provides a single USB configuration +with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and +USB Mass Storage functions. + +Each function can be disabled via a Kconfig option. There's also +a CDC ECM (Ethernet) function which can be turned on. If, however, +CDC ECM and RNDIS are enabled the gadget will have two configurations +-- one with RNDIS and another with CDC ECM[3]. + +Please not, however, that if you use non-standard configuration you +may need to change vendor and/or product ID. + +* Host drivers + +To make use of the gadget one needs to make it work on host side -- +without that there's no hope of achieving anything with the gadget. +As one might expect, things one need to do very from system to system. + +** Linux host drivers + +Since the gadget uses standard composite framework and appears as such +to Linux host it does not need any additional drivers on Linux host +side. All the functions are handled by respective drivers designed +for them. + +This is also true for two configuration set-up with RNDIS +configuration being the first one. Linux host will use the second +configuration with CDC ECM which should work better under Linux. + +** Windows host drivers + +For the gadget two work under Windown two conditions have to be met: + +*** Detecting as composite gadget + +First of all, Windows need to detect the gadget as an USB composite +gadget which on its own have some conditions[4]. If they are met, +Windows lets USB Generic Parent Driver[5] handle the device which then +tries to much drivers for each individual interface (sort of, don't +get into too many details). + +The good news is, you do not have to worry about most of conditions! + +The only thing to worry is that the gadget has to have a single +configuration so a dual RNDIS and CDC ECM gadget won't work unless you +create a proper INF -- and of course, if you do submit it! + +*** Attaching drivers for each function + +The other, trickier thing is making Windows attach drivers to each +individual function. + +For mass storage it is trivial since Windows detect it's an interface +implementing USB Mass Storage class and selects appropriate driver. + +Things are harder with RDNIS and CDC ACM. + +**** RNDIS + +To make Windows select RNDIS drivers for the first function in the +gadget, one needs to use the [[file:gadget_multi_rndis.inf]] file +provided with this document. It "attaches" Window's RNDIS driver to +the first interface of the gadget. + +Please note, that while testing we encountered some issues[6] when +RNDIS was not the first interface. You do not need to worry abut it +unless you are trying to develop your own gadget in which case watch +out for this bug. + +**** CDC ACM + +Similarly, [[file:gadget_multi_serial.inf]] is provided for CDC ACM. +Note, however that it also requires an usbser.sys file which can be +extracted form Windows XP SP3 cab files. + +There is another usbser.sys file floating around the Internet but as +we were testing the gadget it failed to work. It is very likely that +one needs usbser.sys in version intended for one's version of Windows. + +We do net claim to be experts as far as INF files are considered so we +think that there should be a better way of defining files in the +[[file:gadget_multi_serial.inf]] so that it will work regardless of SP +version installed. Again, if you happen to hack a better INF do not +hesitate submitting it! + +**** Customising the gadget + +If you intend to hack the g_multi gadget be advised that rearranging +functions will obviously change interface numbers for each of the +functionality. As an effect provided INFs won't work since they have +interface numbers hard-coded in them (it's not hard to change those +though). + +This also means, that after experimenting with g_multi and changing +provided functions one should change gadget's vendor and/or product ID +so there will be no collision with other customised gadgets or the +original gadget. + +Failing to comply may cause brain damage after wondering for hours why +things don't work as intended before realising Windows have cached +some drivers information (changing USB port may sometimes help). + +**** Improvements in INF files + +It needs to be noted that we are not Windows driver experts and as +such we do not claim that provided INF files are flawless or that they +will work on each and every Windows versions (they were tested on +Windows XP SP3 only). + +The bottom line is, if you can improve the INF files, please do and +share the results[7]. :) + +** Other systems + +At this moment, drivers for any other systems have not been tested. +Knowing how MacOS is based on BSD and BSD is an Open Source it is +believed that it should (read: "I have no idea whether it will") work +out-of-the-box. + +For more exotic systems I have even less to say... + +Any testing and drivers *are* *welcome*! + +* Authors + +This document has been written by Michal Nazarewicz +([[mailto:[email protected]]]) and the INF files have been hacked by +Marek Szyprowski ([[mailto:[email protected]]]) basing on the +[[file:linux.inf]] file provided for Ethernet gadget and description +from [[file:gadget_serial.txt]]. + +* Footnotes + +[1] Remote Network Driver Interface Specification, +[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. + +[2] Communications Device Class Abstract Control Model, spec for this +and other USB classes can be found at +[[http://www.usb.org/developers/devclass_docs/]]. + +[3] CDC Ethernet Control Model. + +[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]]. + +[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]]. + +[6] To put it in some other nice words, Windows failed to respond to +any user input. + +[7] Possibility to say `git rev-list --author='Your Name' +linus/master|wc -l` returns non-zero -- priceless. :] +
Documentation/usb/gadget_multi_rndis.inf new file +200 -0
200 lines not on this page · raw message
Documentation/usb/gadget_multi_serial.inf new file +44 -0
44 lines not on this page · raw message
Signature · 1 line
1.7.1
PATCH v2 6/7 USB: gadget: g_multi: code clean up and refactoring
In reply to Michal NazarewiczThe Multifunction Compasite Gadget have been cleaned up and refactored so hopefully it looks prettier and works at least as good as before changes.
--- drivers/usb/gadget/Kconfig | 1 + drivers/usb/gadget/multi.c | 262 +++++++++++++++++++++++++------------------- 2 files changed, 148 insertions(+), 115 deletions(-)
drivers/usb/gadget/Kconfig +1 -0
@@ -862,6 +862,7 @@ config USB_G_NOKIA config USB_G_MULTI tristate "Multifunction Composite Gadget (EXPERIMENTAL)" depends on BLOCK && NET + select USB_G_MULTI_CDC if ! USB_G_MULTI_RNDIS help The Multifunction Composite Gadget provides Ethernet (RNDIS and/or CDC Ethernet), mass storage and ACM serial link
drivers/usb/gadget/multi.c +147 -115
404 lines not on this page · raw message
Signature · 1 line
1.7.1
PATCH v2 3/7 USB: gadget: f_fs: functionfs_add() renamed to functionfs_bind_config()
In reply to Michal NazarewiczFunctionFS had a bit unique name for function used to add it to USB configuration. Renamed as to match naming convention of other functions.
--- drivers/usb/gadget/f_fs.c | 6 +++--- drivers/usb/gadget/g_ffs.c | 2 +- include/linux/usb/functionfs.h | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-)
drivers/usb/gadget/f_fs.c +3 -3
@@ -1480,9 +1480,9 @@ static void ffs_epfiles_destroy(struct ffs_epfile *epfiles, unsigned count) } -static int functionfs_add (struct usb_composite_dev *cdev, -struct usb_configuration *c, -struct ffs_data *ffs) +static int functionfs_bind_config (struct usb_composite_dev *cdev, +struct usb_configuration *c, +struct ffs_data *ffs) {struct ffs_function *func;int ret;
drivers/usb/gadget/g_ffs.c +1 -1
@@ -388,7 +388,7 @@ static int __gfs_do_config(struct usb_configuration *c,return ret; } - ret =functionfs_add (c->cdev, c, gfs_ffs_data); + ret =functionfs_bind_config (c->cdev, c, gfs_ffs_data);if (unlikely (ret <0 ))return ret;
include/linux/usb/functionfs.h +3 -3
@@ -180,9 +180,9 @@ static int functionfs_bind(struct ffs_data *ffs, struct usb_composite_dev *cdev)static void functionfs_unbind (struct ffs_data *ffs) __attribute__((nonnull)); -static int functionfs_add (struct usb_composite_dev *cdev, -struct usb_configuration *c, -struct ffs_data *ffs) +static int functionfs_bind_config (struct usb_composite_dev *cdev, +struct usb_configuration *c, +struct ffs_data *ffs) __attribute__((warn_unused_result, nonnull));
Signature · 1 line
1.7.1
PATCH v2 5/7 USB: gadget: f_fs: use usb_string_ids_n()
In reply to Michal NazarewiczUse usb_string_ids_n() function to simplify string ids registeration.
--- drivers/usb/gadget/f_fs.c | 30 ++++++++++++------------------ 1 files changed, 12 insertions(+), 18 deletions(-)
drivers/usb/gadget/f_fs.c +12 -18
@@ -1377,7 +1377,8 @@ static void ffs_data_reset(struct ffs_data *ffs)static int functionfs_bind (struct ffs_data *ffs,struct usb_composite_dev *cdev) { -unsigned i, count; +struct usb_gadget_strings **lang; +unsigned first_id;ENTER ();
@@ -1385,7 +1386,9 @@ static int functionfs_bind(struct ffs_data *ffs, struct usb_composite_dev *cdev) || test_and_set_bit(FFS_FL_BOUND, &ffs->flags)))return -EBADFD ; -ffs_data_get (ffs); + first_id =usb_string_ids_n (cdev, ffs->strings_count); +if (unlikely (first_id <0 )) +return first_id; ffs->ep0req =usb_ep_alloc_request (cdev->gadget->ep0,GFP_KERNEL );if (unlikely (!ffs->ep0req))
@@ -1393,25 +1396,16 @@ static int functionfs_bind(struct ffs_data *ffs, struct usb_composite_dev *cdev) ffs->ep0req->complete = ffs_ep0_complete; ffs->ep0req->context = ffs; -/* Get strings identifiers */ -for (count = ffs->strings_count, i =0 ; i < count; ++i) { -struct usb_gadget_strings **lang; - -int id =usb_string_id (cdev); -if (unlikely (id <0 )) { -usb_ep_free_request (cdev->gadget->ep0, ffs->ep0req); - ffs->ep0req =NULL ; -return id; - } - - lang = ffs->stringtabs; -do { - (*lang)->strings[i].id = id; - ++lang; - }while (*lang); + lang = ffs->stringtabs; +while (*lang) { +struct usb_string *str = (*lang)->strings; +int id = first_id; +for (; str->s; ++id, ++str) + str->id = id; } ffs->gadget = cdev->gadget; +ffs_data_get (ffs);return 0 ; }
Signature · 1 line
1.7.1
PATCH v2 4/7 USB: gadget: composite: usb_string_ids_*() functions added
In reply to Michal Nazarewiczusb_string_ids_tab() and usb_string_ids_n() functions added to the composite framework. The first accepts an array of usb_string object and for each registeres a string id and the second registeres a given number of ids and returns the first.
This may simplify string ids registration since gadgets and composite functions won't have to call usb_string_id() several times and each time check for errer status -- all this will be done with a single call.
--- drivers/usb/gadget/composite.c | 67 ++++++++++++++++++++++++++++++++++++++-- include/linux/usb/composite.h | 4 ++ 2 files changed, 68 insertions(+), 3 deletions(-)
drivers/usb/gadget/composite.c +64 -3
@@ -673,9 +673,10 @@ static int get_string(struct usb_composite_dev *cdev,* string IDs. Drivers for functions, configurations, or gadgets will * then store that ID in the appropriate descriptors and string table. * -* All string identifier should be allocated using this routine, to -* ensure that for example different functions don't wrongly assign -* different meanings to the same identifier. +* All string identifier should be allocated using this, +* @usb_string_ids_tab() or @usb_string_ids_n() routine, to ensure +* that for example different functions don't wrongly assign different +* meanings to the same identifier. */ int usb_string_id (struct usb_composite_dev *cdev) {
@@ -687,6 +688,66 @@ int usb_string_id(struct usb_composite_dev *cdev)return -ENODEV ; } +/** +* usb_string_ids() - allocate unused string IDs in batch +* @cdev: the device whose string descriptor IDs are being allocated +* @str: an array of usb_string objects to assign numbers to +* Context: single threaded during gadget setup +* +* @usb_string_ids() is called from bind() callbacks to allocate +* string IDs. Drivers for functions, configurations, or gadgets will +* then copy IDs from the string table to the appropriate descriptors +* and string table for other languages. +* +* All string identifier should be allocated using this, +* @usb_string_id() or @usb_string_ids_n() routine, to ensure that for +* example different functions don't wrongly assign different meanings +* to the same identifier. +*/ +int usb_string_ids_tab (struct usb_composite_dev *cdev,struct usb_string *str) +{ +int next = cdev->next_string_id; + +for (; str->s; ++str) { +if (unlikely (next ==255 )) +return -ENODEV ; + str->id = ++next; + } + + cdev->next_string_id = next; + +return 0 ; +} + +/** +* usb_string_ids_n() - allocate unused string IDs in batch +* @cdev: the device whose string descriptor IDs are being allocated +* @n: number of string IDs to allocate +* Context: single threaded during gadget setup +* +* Returns the first requested ID. This ID and next @n-1 IDs are now +* valid IDs. At least providind that @n is non zore because if it +* is, returns last requested ID which is now very useful information. +* +* @usb_string_ids_n() is called from bind() callbacks to allocate +* string IDs. Drivers for functions, configurations, or gadgets will +* then store that ID in the appropriate descriptors and string table. +* +* All string identifier should be allocated using this, +* @usb_string_id() or @usb_string_ids_n() routine, to ensure that for +* example different functions don't wrongly assign different meanings +* to the same identifier. +*/ +int usb_string_ids_n (struct usb_composite_dev *c,unsigned n) +{ +unsigned next = c->next_string_id; +if (unlikely (n >254 || (unsigned )next + n >255 )) +return -ENODEV ; + c->next_string_id += n; +return next +1 ; +} + +/*-------------------------------------------------------------------------*/ static void composite_setup_complete (struct usb_ep *ep,struct usb_request *req)
include/linux/usb/composite.h +4 -0
@@ -342,6 +342,10 @@ struct usb_composite_dev { };extern int usb_string_id (struct usb_composite_dev *c); +extern int usb_string_ids_tab (struct usb_composite_dev *c, +struct usb_string *str); +extern int usb_string_ids_n (struct usb_composite_dev *c,unsigned n); +/* messaging utils */ #define DBG(d, fmt, args...) \
Signature · 1 line
1.7.1
[PATCHv2.1] USB: gadget: f_fs: use usb_string_ids_n()
In reply to Michal NazarewiczUse usb_string_ids_n() function to simplify string ids registeration.
---
This fixes to silly bugs in my previous patch. One was that first_id was unsigned should "first_id < 0" would be always false and in the "lang" loop I forgot to include ++lang.
drivers/usb/gadget/f_fs.c | 29 +++++++++++------------------ 1 files changed, 11 insertions(+), 18 deletions(-)
drivers/usb/gadget/f_fs.c +11 -18
@@ -1377,7 +1377,8 @@ static void ffs_data_reset(struct ffs_data *ffs)static int functionfs_bind (struct ffs_data *ffs,struct usb_composite_dev *cdev) { -unsigned i, count; +struct usb_gadget_strings **lang; +int first_id;ENTER ();
@@ -1385,7 +1386,9 @@ static int functionfs_bind(struct ffs_data *ffs, struct usb_composite_dev *cdev) || test_and_set_bit(FFS_FL_BOUND, &ffs->flags)))return -EBADFD ; -ffs_data_get (ffs); + first_id =usb_string_ids_n (cdev, ffs->strings_count); +if (unlikely (first_id <0 )) +return first_id; ffs->ep0req =usb_ep_alloc_request (cdev->gadget->ep0,GFP_KERNEL );if (unlikely (!ffs->ep0req))
@@ -1393,25 +1396,15 @@ static int functionfs_bind(struct ffs_data *ffs, struct usb_composite_dev *cdev) ffs->ep0req->complete = ffs_ep0_complete; ffs->ep0req->context = ffs; -/* Get strings identifiers */ -for (count = ffs->strings_count, i =0 ; i < count; ++i) { -struct usb_gadget_strings **lang; - -int id =usb_string_id (cdev); -if (unlikely (id <0 )) { -usb_ep_free_request (cdev->gadget->ep0, ffs->ep0req); - ffs->ep0req =NULL ; -return id; - } - - lang = ffs->stringtabs; -do { - (*lang)->strings[i].id = id; - ++lang; - }while (*lang); +for (lang = ffs->stringtabs; *lang; ++lang) { +struct usb_string *str = (*lang)->strings; +unsigned id = first_id; +for (; str->s; ++id, ++str) + str->id = id; } ffs->gadget = cdev->gadget; +ffs_data_get (ffs);return 0 ; }
Signature · 1 line
1.7.1