#include <linux/bcd.h>
#include <linux/version.h>
#include <linux/usb/ch9.h>
#include <linux/usb/gadget.h>

Data Structures
struct	usb_function

struct	usb_configuration

struct	usb_composite_driver

struct	usb_composite_dev

struct	usb_composite_overwrite

Macros
#define	USB_GADGET_DELAYED_STATUS 0x7fff /* Impossibly large value */

#define	USB_COMP_EP0_BUFSIZ 1024

: For diagnostics, identifies the function.
struct usb_function - describes one function of a configuration : tables of strings, keyed by identifiers assigned during bind() and by language IDs provided in control requests : Table of full (or low) speed descriptors, using interface and string identifiers assigned during (). If this pointer is null, the function will not be available at full speed (or at low speed). : Table of high speed descriptors, using interface and string identifiers assigned during (). If this pointer is null, the function will not be available at high speed. : Table of super speed descriptors, using interface and string identifiers assigned during (). If this pointer is null after initiation, the function will not be available at super speed. : assigned when () is called; this is the configuration with which this function is associated. : Before the gadget can register, all of its functions bind() to the available resources including string and interface identifiers used in interface or class descriptors; endpoints; I/O buffers; and so on. : Reverses ; called as a side effect of unregistering the driver which added this function. : (REQUIRED) Reconfigures altsettings; function drivers may initialize usb_ep.driver data at this time (when it is used). Note that setting an interface to its current altsetting resets interface state, and that all interfaces have a disabled state. : Returns the active altsetting. If this is not provided, then only altsetting zero is supported. : (REQUIRED) Indicates the function should be disabled. Reasons include host resetting or reconfiguring the gadget, and disconnection. : Used for interface-specific control requests. : Notifies functions when the host stops sending USB traffic. : Notifies functions when the host restarts USB traffic. : Returns function status as a reply to GetStatus() request when the recepient is Interface. : callback to be called when SetFeature(FUNCTION_SUSPEND) is reseived A single USB function uses one or more interfaces, and should in most cases support operation at both full and high speeds. Each function is associated by () with a one configuration; that function causes () to be called so resources can be allocated as part of setting up a gadget driver. Those resources include endpoints, which should be allocated using (). To support dual speed operation, a function driver provides descriptors for both high and full speed operation. Except in rare cases that don't involve bulk endpoints, each speed needs different endpoint descriptors. Function drivers choose their own strategies for managing instance data. The simplest strategy just declares it "static', which means the function can only be activated once. If the function needs to be exposed in more than one configuration at a given speed, it needs to support multiple usb_function structures (one for each configuration). A more complex strategy might encapsulate a structure inside a driver-specific instance structure to allows multiple activations. An example of multiple activations might be a CDC ACM function that supports two or more distinct instances within the same configuration, providing several independent logical data links to a USB host.
#define	MAX_CONFIG_INTERFACES 16 /* arbitrary; max 255 */

enum	{ USB_GADGET_MANUFACTURER_IDX = 0, USB_GADGET_PRODUCT_IDX, USB_GADGET_SERIAL_IDX, USB_GADGET_FIRST_AVAIL_IDX }

int	usb_add_function (struct usb_configuration , struct usb_function )

int	usb_function_deactivate (struct usb_function *)

int	usb_function_activate (struct usb_function *)

int	usb_interface_id (struct usb_configuration , struct usb_function )

int	config_ep_by_speed (struct usb_gadget g, struct usb_function f, struct usb_ep *_ep)

int	usb_add_config (struct usb_composite_dev , struct usb_configuration , int()(struct usb_configuration ))

void	usb_remove_config (struct usb_composite_dev , struct usb_configuration )

: For diagnostics, identifies the driver.
struct usb_composite_driver - groups configurations into a gadget : Template descriptor for the device, including default device identifiers. : tables of strings, keyed by identifiers assigned during and language IDs provided in control requests. Note: The first entries are predefined. The first entry that may be used is USB_GADGET_FIRST_AVAIL_IDX : Highest speed the driver supports. : set to 1 if the gadget needs userspace to provide a serial number. If one is not provided, warning will be printed. : (REQUIRED) Used to allocate resources that are shared across the whole device, such as string IDs, and add its configurations using (). This may fail by returning a negative errno value; it should return zero on successful initialization. : Reverses ; called as a side effect of unregistering this driver. : optional driver disconnect method : Notifies when the host stops sending USB traffic, after function notifications : Notifies configuration when the host restarts USB traffic, before function notifications Devices default to reporting self powered operation. Devices which rely on bus powered operation should report this in their method. Before returning from , various fields in the template descriptor may be overridden. These include the idVendor/idProduct/bcdDevice values normally to bind the appropriate host side driver, and the three strings (iManufacturer, iProduct, iSerialNumber) normally used to provide user meaningful device identifiers. (The strings will not be defined unless they are defined in and .) The correct ep0 maxpacket size is also reported, as defined by the underlying controller driver.
#define	USB_GADGET_COMPOSITE_OPTIONS()

#define	DBG(d, fmt, args...) dev_dbg(&(d)->gadget->dev , fmt , ## args)

#define	VDBG(d, fmt, args...) dev_vdbg(&(d)->gadget->dev , fmt , ## args)

#define	ERROR(d, fmt, args...) dev_err(&(d)->gadget->dev , fmt , ## args)

#define	WARNING(d, fmt, args...) dev_warn(&(d)->gadget->dev , fmt , ## args)

#define	INFO(d, fmt, args...) dev_info(&(d)->gadget->dev , fmt , ## args)

int	usb_composite_probe (struct usb_composite_driver *driver)

void	usb_composite_unregister (struct usb_composite_driver *driver)

void	usb_composite_setup_continue (struct usb_composite_dev *cdev)

int	usb_string_id (struct usb_composite_dev *c)

int	usb_string_ids_tab (struct usb_composite_dev c, struct usb_string str)

int	usb_string_ids_n (struct usb_composite_dev *c, unsigned n)

void	usb_composite_overwrite_options (struct usb_composite_dev cdev, struct usb_composite_overwrite covr)

Macro Definition Documentation

#define DBG	(	d,
		fmt,
		args...
	)	dev_dbg(&(d)->gadget->dev , fmt , ## args)

Definition at line 433 of file composite.h.

#define ERROR	(	d,
		fmt,
		args...
	)	dev_err(&(d)->gadget->dev , fmt , ## args)

Definition at line 437 of file composite.h.

#define INFO	(	d,
		fmt,
		args...
	)	dev_info(&(d)->gadget->dev , fmt , ## args)

Definition at line 441 of file composite.h.

#define MAX_CONFIG_INTERFACES 16 /* arbitrary; max 255 */

Definition at line 169 of file composite.h.

#define USB_COMP_EP0_BUFSIZ 1024

Definition at line 52 of file composite.h.

#define USB_GADGET_COMPOSITE_OPTIONS ( )

Value:

static struct usb_composite_overwrite coverwrite;       \
									\
	module_param_named(idVendor, coverwrite.idVendor, ushort, S_IRUGO); \
    MODULE_PARM_DESC(idVendor, "USB Vendor ID");            \
									\
	module_param_named(idProduct, coverwrite.idProduct, ushort, S_IRUGO); \
    MODULE_PARM_DESC(idProduct, "USB Product ID");          \
									\
	module_param_named(bcdDevice, coverwrite.bcdDevice, ushort, S_IRUGO); \
    MODULE_PARM_DESC(bcdDevice, "USB Device version (BCD)");    \
									\
	module_param_named(iSerialNumber, coverwrite.serial_number, charp, \
            S_IRUGO); \
    MODULE_PARM_DESC(iSerialNumber, "SerialNumber string");     \
									\
	module_param_named(iManufacturer, coverwrite.manufacturer, charp, \
            S_IRUGO); \
    MODULE_PARM_DESC(iManufacturer, "USB Manufacturer string"); \
									\
	module_param_named(iProduct, coverwrite.product, charp, S_IRUGO); \
    MODULE_PARM_DESC(iProduct, "USB Product string")

Definition at line 397 of file composite.h.

#define USB_GADGET_DELAYED_STATUS 0x7fff /* Impossibly large value */

Definition at line 49 of file composite.h.

#define VDBG	(	d,
		fmt,
		args...
	)	dev_vdbg(&(d)->gadget->dev , fmt , ## args)

Definition at line 435 of file composite.h.

#define WARNING	(	d,
		fmt,
		args...
	)	dev_warn(&(d)->gadget->dev , fmt , ## args)

Definition at line 439 of file composite.h.

Enumeration Type Documentation

anonymous enum

Enumerator:

USB_GADGET_MANUFACTURER_IDX
USB_GADGET_PRODUCT_IDX
USB_GADGET_SERIAL_IDX
USB_GADGET_FIRST_AVAIL_IDX

Definition at line 254 of file composite.h.

Function Documentation

int config_ep_by_speed	(	struct usb_gadget *	g,
		struct usb_function *	f,
		struct usb_ep *	_ep
	)

config_ep_by_speed() - configures the given endpoint according to gadget speed. : pointer to the gadget : usb function : the endpoint to configure

Return: error code, 0 on success

This function chooses the right descriptors for a given endpoint according to gadget speed and saves it in the endpoint desc field. If the endpoint already has a descriptor assigned to it - overwrites it with currently corresponding descriptor. The endpoint maxpacket field is updated according to the chosen descriptor. Note: the supplied function should hold all the descriptors for supported speeds

Definition at line 115 of file composite.c.

int usb_add_config	(	struct usb_composite_dev *	cdev,
		struct usb_configuration *	config,
		int()(struct usb_configuration )	bind
	)

usb_add_config() - add a configuration to a device. : wraps the USB gadget : the configuration, with bConfigurationValue assigned : the configuration's bind function Context: single threaded during gadget setup

One of the main tasks of a composite () routine is to add each of the configurations it supports, using this routine.

This function returns the value of the configuration's (), which is zero for success else a negative errno value. Binding configurations assigns global resources including string IDs, and per-configuration resources such as interface IDs and endpoints.

Definition at line 713 of file composite.c.

int usb_add_function	(	struct usb_configuration *	config,
		struct usb_function *	function
	)

usb_add_function() - add a function to a configuration : the configuration : the function being added Context: single threaded during gadget setup

After initialization, each configuration must have one or more functions added to it. Adding a function involves calling its () method to allocate resources such as interface and string identifiers and endpoints.

This function returns the value of the function's bind(), which is zero for success else a negative errno value.

Definition at line 209 of file composite.c.

void usb_composite_overwrite_options	(	struct usb_composite_dev *	cdev,
		struct usb_composite_overwrite *	covr
	)

Definition at line 1653 of file composite.c.

int usb_composite_probe ( struct usb_composite_driver * driver )

usb_composite_probe() - register a composite driver : the driver to register : the callback used to allocate resources that are shared across the whole device, such as string IDs, and add its configurations using (). This may fail by returning a negative errno value; it should return zero on successful initialization. Context: single threaded during gadget setup

This function is used to register drivers using the composite driver framework. The return value is zero, or a negative errno value. Those values normally come from the driver's method, which does all the work of setting up the driver to match the hardware.

On successful return, the gadget is ready to respond to requests from the host, unless one of its components invokes usb_gadget_disconnect() while it was binding. That would usually be done in order to wait for some userspace participation.

Definition at line 1622 of file composite.c.

void usb_composite_setup_continue ( struct usb_composite_dev * cdev )

usb_composite_setup_continue() - Continue with the control transfer : the composite device who's control transfer was kept waiting

This function must be called by the USB function driver to continue with the control transfer's data/status stage in case it had requested to delay the data/status stages. A USB function's setup handler (e.g. set_alt()) can request the composite framework to delay the setup request's data/status stages by returning USB_GADGET_DELAYED_STATUS.

Definition at line 1663 of file composite.c.

void usb_composite_unregister ( struct usb_composite_driver * driver )

usb_composite_unregister() - unregister a composite driver : the driver to unregister

This function is used to unregister drivers using the composite driver framework.

Definition at line 1646 of file composite.c.

int usb_function_activate ( struct usb_function * function )

usb_function_activate - allow function and gadget enumeration : function on which usb_function_activate() was called

Reverses effect of usb_function_deactivate(). If no more functions are delaying their activation, the gadget driver will respond to host enumeration procedures.

Returns zero on success, else negative errno.

Definition at line 299 of file composite.c.

int usb_function_deactivate ( struct usb_function * function )

usb_function_deactivate - prevent function and gadget enumeration : the function that isn't yet ready to respond

Blocks response of the gadget driver to host enumeration by preventing the data line pullup from being activated. This is normally called during () processing to change from the initial "ready to respond" state, or when a required resource becomes available.

For example, drivers that serve as a passthrough to a userspace daemon can block enumeration unless that daemon (such as an OBEX, MTP, or print server) is ready to handle host requests.

Not all systems support software control of their USB peripheral data pullups.

Returns zero on success, else negative errno.

Definition at line 272 of file composite.c.

int usb_interface_id	(	struct usb_configuration *	config,
		struct usb_function *	function
	)

usb_interface_id() - allocate an unused interface ID : configuration associated with the interface : function handling the interface Context: single threaded during gadget setup

usb_interface_id() is called from usb_function.bind() callbacks to allocate new interface IDs. The function driver will then store that ID in interface, association, CDC union, and other descriptors. It will also handle any control requests targeted at that interface, particularly changing its altsetting via set_alt(). There may also be class-specific or vendor-specific requests to handle.

All interface identifier should be allocated using this routine, to ensure that for example different functions don't wrongly assign different meanings to the same identifier. Note that since interface identifiers are configuration-specific, functions used in more than one configuration (or more than once in a given configuration) need multiple versions of the relevant descriptors.

Returns the interface ID which was allocated; or -ENODEV if no more interface IDs can be allocated.

Definition at line 342 of file composite.c.

void usb_remove_config	(	struct usb_composite_dev *	cdev,
		struct usb_configuration *	config
	)

usb_remove_config() - remove a configuration from a device. : wraps the USB gadget : the configuration

Drivers must call usb_gadget_disconnect before calling this function to disconnect the device from the host and make sure the host will not try to enumerate the device while we are changing the config list.

Definition at line 826 of file composite.c.

int usb_string_id ( struct usb_composite_dev * cdev )

usb_string_id() - allocate an unused string ID : the device whose string descriptor IDs are being allocated Context: single threaded during gadget setup

() 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, () or () routine, to ensure that for example different functions don't wrongly assign different meanings to the same identifier.

Definition at line 995 of file composite.c.

int usb_string_ids_n	(	struct usb_composite_dev *	c,
		unsigned	n
	)

usb_string_ids_n() - allocate unused string IDs in batch : the device whose string descriptor IDs are being allocated
: number of string IDs to allocate Context: single threaded during gadget setup

Returns the first requested ID. This ID and next
-1 IDs are now valid IDs. At least provided that
is non-zero because if it is, returns last requested ID which is now very useful information.

() 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, () or () routine, to ensure that for example different functions don't wrongly assign different meanings to the same identifier.

Definition at line 1057 of file composite.c.

int usb_string_ids_tab	(	struct usb_composite_dev *	cdev,
		struct usb_string *	str
	)

usb_string_ids() - allocate unused string IDs in batch : the device whose string descriptor IDs are being allocated : an array of usb_string objects to assign numbers to Context: single threaded during gadget setup

() 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, () or () routine, to ensure that for example different functions don't wrongly assign different meanings to the same identifier.

Definition at line 1023 of file composite.c.

Data Structures

Macros

: For diagnostics, identifies the function.

: For diagnostics, identifies the driver.

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation