USB Device Multiplexer (UDM)
[USB Device Framework]

Collaboration diagram for USB Device Multiplexer (UDM):

Data Structures
struct	udm_interface
	A USB device interface. More...
struct	udm_config
	A USB device configuration. More...
Configuration Management
The following functions may be called by the application to create configurations and associate interfaces with them. The interface objects are typically returned by the initialization function of a USB Device Interface Driver. udm_create_config() returns a configuration object which can be passed as a parameter to the other configuration management functions. The configuration descriptor is managed by the UDM layer, but the application may alter certain fields by calling udm_config_set_self_powered(), udm_config_set_bus_powered(), and udm_config_set_max_power(). The application must not create more than one configuration with a given value, and it must not attempt to create more configurations than specified by APP_USB_DEVICE_NR_CONFIGS.
void	udm_config_add_interface (struct udm_config config, struct udm_interface iface)
	Add an interface to a configuration.
struct udm_config *	udm_create_config (uint8_t value, uint8_t nr_interfaces)
	Create a new USB device configuration.
void	udm_config_set_max_power (struct udm_config *config, unsigned int milliamps)
	Set the maximum power consumption of a configuration.
void	udm_config_set_self_powered (struct udm_config *config)
	Mark a configuration as self-powered.
void	udm_config_set_bus_powered (struct udm_config *config)
	Mark a configuration as bus-powered.
USB String Descriptor Support
The following functions may be used by the application to implement support for USB string descriptors. Such descriptors are optional according to the USB spec, so by default, all string descriptor requests are rejected. To support string descriptors, the application must implement the function app_usb_get_string_descriptor() and provide a preprocessor define named `HAVE_APP_USB_GET_STRING_DESCRIPTOR` (which will disable the default implementation).
int	udm_submit_utf16le_string_desc (struct udc udc, struct usb_request req, const le16_t *str, uint16_t max_len)
	Add a string descriptor buffer initialized from a UTF-16LE encoded string.
int	udm_submit_ascii_string_desc (struct udc udc, struct usb_request req, const char *str, uint16_t max_len)
	Add a string descriptor buffer initialized from an 8-bit ASCII encoded string.
static int	app_usb_get_string_descriptor (struct udc udc, struct usb_request req, uint8_t index, uint16_t langid, uint16_t len)
	Application-specific hook for retrieving a USB String descriptor.
USB Device Strings

#define	USB_STRING_DEV_PRODUCT 0
	String ID representing the name of the product.
#define	USB_STRING_DEV_SERIAL 0
	String ID representing the serial number of the device.

Detailed Description

The USB Device Multiplexer (UDM) keeps track of configurations, interfaces and settings, and switches between them based on requests received from the host.

A USB device can have one or more configurations, which the host can choose between using the standard Set Configuration request. The host can also choose not to enable any configuration by selecting the special configuration ID 0. Each configuration can have one or more interfaces, which are all active at the same time. Each interface can have one or more alternate settings which the host can choose between using the standard Set Interface request.

The Device Descriptor

The USB Device Multiplexer provides a Device Descriptor for the device. The contents of this can be specified by defining the following macros in app/usb.h. Please see the USB Specification for more information about the meaning of the fields.

APP_USB_DEVICE_CLASS: bDeviceClass
APP_USB_DEVICE_SUBCLASS: bDeviceSubClass
APP_USB_DEVICE_PROTOCOL: bDeviceProtocol
APP_UDC_MAXPACKETSIZE0: bMaxPacketSize0 (also used by UDC driver)
APP_USB_DEVICE_VENDOR_ID: idVendor
APP_USB_DEVICE_PRODUCT_ID: idProduct
APP_USB_DEVICE_MAJOR_VERSION / APP_USB_DEVICE_MINOR_VERSION: bcdDevice
APP_USB_DEVICE_NR_CONFIGS: bNumConfigurations

Strings in the Device Descriptor

The application may define the following string IDs (and add support for string descriptors as explained below) to allow the host to display user-friendly strings whenever the device is connected:

USB_STRING_DEV_MANUFACTURER: iManufacturer
USB_STRING_DEV_PRODUCT: iProduct
USB_STRING_DEV_SERIAL: iSerialNumber

USB String Descriptor Support

The following example illustrates how to implement support for string descriptors in an application. Note that the value passed in the langid parameter is in native byte order, not little endian.

apps/foo/main.c (or somewhere else)

 static const le16_t langid_str[] = {
        LE16(USB_LANGID_EN_US),
        LE16(0),        // Terminate the list
 };
 static const char *string_table[] = {
        NULL,           // LANGID
        "This is my device",
 };

 int app_usb_get_string_descriptor(struct udc *udc,
                struct usb_request *req, uint8_t index,
                uint16_t langid, uint16_t len)
 {
        if (index >= ARRAY_LEN(string_table))
                return ERR_INVALID_ARG;
        if (index != 0 && langid != USB_LANGID_EN_US)
                return ERR_INVALID_ARG;

        if (index == 0)
                return udm_submit_utf16le_string_desc(udc, req,
                        langid_str, len);

        return udm_submit_ascii_string_desc(udc, req,
                string_table[index], len);
 }

apps/foo/include/app/usb.h

 extern int app_usb_get_string_descriptor(struct udc *udc,
                struct usb_request *req, uint8_t index,
                uint16_t langid, uint16_t len);
 #define HAVE_APP_USB_GET_STRING_DESCRIPTOR

USB Device Interface (UDI) drivers

An interface is represented by an instance of struct udm_interface, implemented by a USB Device Interface (UDI) driver. The UDM layer dispatches various requests received from the host to the UDI driver through the function pointers in that structure.

When an interface setting has been enabled, the driver may interact directly with the UDC driver, managing endpoints and submitting requests on them. The UDI driver may only submit control transfers when it is processing a SETUP request directed at its interface.

Note that the function driver must never keep any endpoints active after udm_interface::disable() has been called. When the host re-selects the currently active interface setting using Set Interface, the UDM will call udm_interface::enable(). The UDI driver is responsible for disabling and re-enabling itself when udm_interface::enable() is called and the interface is already active.

Define Documentation

#define USB_STRING_DEV_PRODUCT 0

String ID representing the name of the product.

The value of this define is stored in the iProduct field of the device and device qualifier descriptors.

Definition at line 194 of file dev_mux.c.

#define USB_STRING_DEV_SERIAL 0

String ID representing the serial number of the device.

The value of this define is stored in the iSerialNumber field of the device and device qualifier descriptors.

Definition at line 197 of file dev_mux.c.

Function Documentation

int app_usb_get_string_descriptor	(	struct udc *	udc,
		struct usb_request *	req,
		uint8_t	index,
		uint16_t	langid,
		uint16_t	len
	)			`[static]`

Application-specific hook for retrieving a USB String descriptor.

The default implementation of this hook will reject all string descriptor requests. If an application needs to support string descriptors, it must implement this function and define the preprocessor symbol HAVE_APP_USB_GET_STRING_DESCRIPTOR.

Parameters:

	udc	The USB Device Controller
	req	The USB request which will be used to send the descriptor
	index	The index of the requested string
	langid	The requested language ID
	len	The maximum number of bytes in the response

Returns:: The number of bytes added to req or a negative error code on failure.

Definition at line 587 of file dev_mux.c.

void udm_config_add_interface	(	struct udm_config *	config,
		struct udm_interface *	iface
	)

Add an interface to a configuration.

This function will associate an interface with an existing configuration so that it will be automatically enabled when the configuration is selected, and the interface descriptor(s) will be included in the configuration descriptor for this configuration.

If no high-speed descriptors are provided, they will be assumed to be the same as the full-speed descriptors.

Parameters:

	config	The USB function configuration.
	iface	The interface to be added to config.

Precondition:

iface must have at least one alternate setting.
iface must have a bInterfaceNumber less than bNumInterfaces of config.
An interface with the same bInterfaceNumber must not have been registered before to the same configuration.
All settings must have the same bInterfaceNumber.
Each setting's high-speed descriptor, if present, must have the same bInterfaceNumber as the full-speed descriptor.

Referenced by dataflash_init().

void udm_config_set_bus_powered ( struct udm_config * config )

Mark a configuration as bus-powered.

Parameters:

config

A USB device configuration

Referenced by dataflash_init().

void udm_config_set_max_power	(	struct udm_config *	config,
		unsigned int	milliamps
	)

Set the maximum power consumption of a configuration.

Parameters:

	config	A USB device configuration
	milliamps	The new maximum power consumption in milliamperes

Referenced by dataflash_init().

void udm_config_set_self_powered ( struct udm_config * config )

Mark a configuration as self-powered.

Parameters:

config

A USB device configuration

struct udm_config * udm_create_config	(	uint8_t	value,
		uint8_t	nr_interfaces
	)			`[read]`

Create a new USB device configuration.

This function will create a new configuration and add it to the array of possible configurations of the device.

Initially, the configuration will be marked as self-powered and drawing 4 mA from the bus.

Parameters:

	value	The value used to select this configuration
	nr_interfaces	The number of interfaces in this configuration

Returns:: An object representing the new configuration.

Precondition:

value is not zero (this configuration value is reserved for representing no active configuration.)
value is not higher than APP_USB_DEVICE_NR_CONFIGS
No configuration with the same value has been registered before.

Referenced by dataflash_init().

int udm_submit_ascii_string_desc	(	struct udc *	udc,
		struct usb_request *	req,
		const char *	str,
		uint16_t	max_len
	)

Add a string descriptor buffer initialized from an 8-bit ASCII encoded string.

Parameters:

	udc	The USB Device Controller
	req	The USB request to which the buffer should be added
	str	A ASCII encoded NUL-terminated string
	max_len	Maximum number of bytes available for the descriptor

Returns:: The number of bytes actually queued, or a negative error code on failure.

int udm_submit_utf16le_string_desc	(	struct udc *	udc,
		struct usb_request *	req,
		const le16_t *	str,
		uint16_t	max_len
	)

Add a string descriptor buffer initialized from a UTF-16LE encoded string.

Parameters:

	udc	The USB Device Controller
	req	The USB request to which the buffer should be added
	str	A UTF-16 LE encoded NUL-terminated string
	max_len	Maximum number of bytes available for the descriptor

Returns:: The number of bytes actually queued, or a negative error code on failure.

USB Device Multiplexer (UDM) [USB Device Framework]

Data Structures

Configuration Management

USB String Descriptor Support

USB Device Strings

Detailed Description

The Device Descriptor

Strings in the Device Descriptor

USB String Descriptor Support

USB Device Interface (UDI) drivers

Define Documentation

Function Documentation

USB Device Multiplexer (UDM)
[USB Device Framework]