LWN: Comments on "The USB composite framework"

The USB composite framework

cladisch — Wed, 22 Jul 2015 09:33:51 +0000

This framework is for gadget drivers.

Loading the drivers one after the other would modify the device's descriptors, which would require a reset to tell the host about the changes.
In any case, even supposedly independet interfaces need to coordinate with each other because they share interface/endpoint/string numbers.

The USB composite framework

sebastien536 — Tue, 21 Jul 2015 17:51:42 +0000

Hello !
I wonder something about USB composite devices. What's the point of using a USB composite driver instead of modprobing several USB drivers ? If we just pay attention that each USB drivers has a different major number, we will be able to modprobe them one by one isnt it ? Or am I wrong ?

Thanks in advance for your answers

The USB composite framework

jimparis — Mon, 05 Nov 2012 23:48:18 +0000

I think USB_DT_PIPE_USAGE is related to UAS (USB Attached SCSI). Maybe "lsusb -vvv" on a Linux host can parse the descriptor better.

The USB composite framework

DABraun — Mon, 05 Nov 2012 22:58:10 +0000

What is it about the Device Descriptor that makes it a composite device?

I created one of your composite devices on a Freescale based embedded system and looked at the device descriptor on the host (Windows) side and there are a number of "Unknown Descriptors" looking like
Unknown Descriptor:
bDescriptorType: 0x24
bLength: 0x05
05 24 00 10 01
(this is from MS usbview.exe utility)
What are these? The descriptor type 0x24 is from the USB 3 spec and is called "USB_DT_PIPE_USAGE" - I searched for this in the 2.6.29.4 sources and couldn't find any references. This leads me to think some trash has been included in the device decriptors. But then again I could have missed something.

Any ideas?

The USB composite framework

DABraun — Mon, 05 Nov 2012 20:40:46 +0000

Ah - didn't see the path - thanks

The USB composite framework

jimparis — Mon, 29 Oct 2012 21:03:05 +0000

Look at the link: it's just drivers/usb/gadget/mass_storage.c in the kernel. In Linus's tree, it would be here.

The USB composite framework

DABraun — Mon, 29 Oct 2012 20:12:58 +0000

I just ran across this article and tried to follow the link to your Mass Storage Gadget. It's broken. Is the source still available somewhere?

The USB composite framework

spectrum — Wed, 09 Mar 2011 21:35:51 +0000

I would like to create a USB composite driver that has functionalities of both file storage gadget and RNDIS gadget.

Is this possible?

The USB composite framework

mina86 — Sun, 25 Jul 2010 11:53:10 +0000

Yep! It would.

As a matter of fact, I've been thinking about something like that for quite some time now (ever since I've started working on USB gadgets I think). I also have some ideas regarding such functionality.

I was thinking more along the lines that you modprobe a stub gadget which merely describes what configurations it want to support and then modprobe all the functions. In essence that's what you've described.

I hope to find time for actually implementing it so maybe it'll be even easier then before to write gadgets. :)

The USB composite framework

mina86 — Sun, 25 Jul 2010 11:49:25 +0000

As I've mentioned, Mass Storage Function is merely a conversion of the File-Storage Gadget so most of the code in MSF is copied with modifications from FSG. As such, your understanding is correct, by MSF I mean all the functions in f_mass_storage.c as well as storage_common.c (the latter is code that is identical (or nearly identical) in both MSF and FSG).

The prefix of the function names may be confusing. At one point I even wanted to use fsg_ for FSG stuff, msf_ for MSF stuff and stor_ for commons but Alan convinced my that it's too much hustle and modification not worth the effort. Hence, the fsg_ prefix stayed.

As far as including .c files... to be honest, I'm not entirely convinced why this is done this way but that's the way it is done in other composite gadget drivers as well. The comment you may find in those is:

> Kbuild is not very cooperative with respect to linking separately compiled library objects into one module. So for now we won't use separate compilation ... ensuring init/exit sections work to shrink the runtime footprint, and giving us at least some parts of what a "gcc --combine ... part1.c part2.c part3.c ... " build would.

Going further in your comment, the situation with composite is just like iabervon described. It makes uninteresting things trivial. I would also add that it makes the more interesting part a bit harder.

This is because composite function has to worry about registering interface and string IDs and never knows in how many configurations it will be present or ever how many configurations gadget has.

One of the most complicated thing about converting File-Storage Gadget to Mass Storage Function was to allow for it to be added to several USB configurations. To achieve that I have created the fsg_common structure with reference counting and some such.

As of next articles I can only thank you for interest and get back to work. ;) Nonetheless, the my next article probably won't cover most of your questions but should be valuable addition to this one.

I may only quickly point out that you deal with hardware limitations by obeying them. :P If your UDC has limited number of endpoints you won't be able to stash many composite functions in a single configuration in your gadget. Mass storage is rather simple since in bulk-only mode (the one implemented by MSF) it uses only one IN and one OUT endpoint but generally functions may need more endpoints.

The USB composite framework

pabs — Fri, 16 Jul 2010 04:38:44 +0000

It would be great to be able to modprobe a mass-storage gadget, a serial gadget and a network gadget and a userland gadget and instantly get a composite device that supports all four.

The USB composite framework

iabervon — Thu, 15 Jul 2010 18:38:54 +0000

I guess this article mostly is focused on how to use the composite framework, but the actual implementation of the device (MSF/FSG/whatever) seems to be the more interesting part from a USB driver writer point of view. Does the composite framework make that part any easier?

My impression is that the framework is not intended to make the interesting part any easier, but rather to make the uninteresting part trivial. Having written a USB gadget (not on Linux), I've found that handling EP0 is a big chunk of uninteresting code that needs to be correct and involves fiddly interactions with your drivers, in that you have to make sure that your driver, your descriptor as sent on EP0, and your hardware registers all agree on how the endpoints are configured, and weird things happen if they don't.

The USB composite framework

jimparis — Thu, 15 Jul 2010 16:16:31 +0000

I'm finding this article very confusing.
When you say things like "The really hard work is done inside the MSF", it sounds like you're talking about the fsg_* functions, which are separate (but mostly copied) from Alan Stern's FSG? So a function like fsg_main_thread in f_mass_storage.c is part of MSF, but the function
fsg_main_thread in file_storage.c is part of FSG?

Having 5 ".c" files #included directly in "the full source code" doesn't help clarify things. Doesn't that also cause symbol conflicts if we wanted to write two modules and install them both?

I guess this article mostly is focused on how to use the composite framework, but the actual implementation of the device (MSF/FSG/whatever) seems to be the more interesting part from a USB driver writer point of view. Does the composite framework make that part any easier?

I'd really look forward to a future article on "more powerful gadgets" as you mention. Particularly interesting would be how such a composite gadget is treated and works on typical operating systems (can each function usually be bound to a driver independently?) and how to deal with hardware limitations (as I understand, most hardware has various limitations on numbers of endpoints or restricts their sizes, etc).

The USB composite framework

linusw — Thu, 15 Jul 2010 09:31:52 +0000

The first part of the article looks very inspired by the Wikipedia article on USB so why not link it:
http://en.wikipedia.org/wiki/Universal_Serial_Bus