Documentation/usb/gadget_multi.rst

Source file repositories/reference/linux-study-clean/Documentation/usb/gadget_multi.rst

File Facts

System
Linux kernel
Corpus path
Documentation/usb/gadget_multi.rst
Extension
.rst
Size
5672 bytes
Lines
166
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

==============================
Multifunction Composite Gadget
==============================

Overview
========

The Multifunction Composite Gadget (or g_multi) is a composite gadget
that makes extensive use of the composite framework to provide
a... multifunction gadget.

In its 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.

A CDC ECM (Ethernet) function may be turned on via a Kconfig option
and RNDIS can be turned off.  If they are both enabled the gadget will
have two configurations -- one with RNDIS and another with CDC ECM[3].

Please note that if you use non-standard configuration (that is enable
CDC ECM) 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 developed
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 to work under Windows 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 match 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 the
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!

Installing drivers for each function
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The other, trickier thing is making Windows install drivers for 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.

Annotation

Implementation Notes