Composite Function

Framework for USB

​

Using Composite Functions

Belcarra Technologies (2005) Corp.

​

June 5, 2008

www.belcarra.com

Overview Plan

This presentation is divided into the following sections:

1. The IAD model -- a way for USB hosts to divide multifunction USB devices into single-function virtual devices
2. hid2 - a simplest example of Belcarra implementation of IAD
3. Class and vendor USB drivers on USB hosts, and different principles for matching them to virtual functions
4. Some examples from Belcarra with more complex host driver requirements
5. IAD Descriptors -- the low-level details
6. Belcarra interface functions -- review of general principles
7. Simple steps to a custom version of generic_cf for a target device, both host-side and target side.

www.belcarra.com

The IAD model - basics

USB hosts decompose a USB device of class USB_CLASS_MISC (0EFh) into smaller virtual devices using Internet Association (IAD) descriptors

• the virtual device descriptor is based on the physical device descriptor with some changes from the corresponding IAD descriptor
• The IAD descriptor specifies the position of the first interface in a function (bFirstInterface), and the number of consecutive interfaces in the function (bInterfaceCount).
• The host OS uses the virtual device descriptor plus bFirst Interface to identify a matching host driver
• Within the host virtual device, virtual interface x is mapped to physical device interface bFirstInterface+x

www.belcarra.com

The IAD model - Device Descriptors

In the IAD model, the host OS builds a virtual descriptor for each virtual device based on the actual device descriptor for

the device

• The process begins with a copy of the physical device descriptor
• The fields bDeviceClass, bDeviceSubClass, bDeviceProtocol in the virtual descriptor are overwritten
• with bFunctionClass, bFunctionSubClass, bFunctionProtocol
• In Belcarra composite configurations, these values are derived from the Device Descriptor fields of the
• suppporting interface function (msc-if, eem-if, etc)
• Vendor ID, Product ID remain the same as the physical device

​

www.belcarra.com

The IAD model - interface indexing

For host OS matching rules, it is very important to know the value of bFirstInterface for all functions. On the host side bFirstInterface is known as MI (matching interface)

​

Example, if there are three functions then

bFirstInterface[0]=0

bFirstInterface[1]=bFirstInterface[0]+bInterfaceCount[0]

bFirstInterface[2]=bFirstInterface[1]+bInterfaceCount[1]

The values of bInterfaceCount in turn depend on the protocol:

mouse.interfaceCount=1

msc.interfaceCount=1

eem.interfaceCount=1

ecm.interfaceCount=2

acm.interfaceCount=2

​

www.belcarra.com

Configuration 1: hid2

Interface functions:mouse-if:mouse-if

• configuration "hid2" has 2 instances of interface function "mouse-if".
• each instance of "mouse-if" uses 1 interface
• the USB host sees 2 random mouse devices
• Microsoft Windows hosts have HID class drivers (see next slide for more about class drivers) built in, and therefore this composite configuration does not require prior preparation of a Windows host

www.belcarra.com

Class drivers

• A class driver is a host OS USB driver with two major properties
• It supports a published specification approved by the USB Implementers Forum (USB-IF)
• The host OS matches the driver to USB function or subfunction using the published Class, Subclass, and Protocol values, independent of Vendor and Product ID
• If a class driver is available, the corresponding USB functions can appear anywhere in a IAD composite configuration without specific configuration of the host OS (match any value of bFirstInterface/MI)
• Major host OS vendors (e.g. Microsoft) do not allow third parties to create class drivers

​

Vendor drivers

All other USB drivers are vendor drivers.

• For this purpose, Microsoft's USBSER.sys is a vendor driver
• Belcarra's USBLAN is a vendor driver which matches several network protocols described in the CDC 1.2 suite.
• Modern host OS's provide a mechanism to associate a vendor driver with a specific IAD interface group in a device

Configuration 2: hid-serial

Interface functions: mouse-if:tty-if

Interface 0

• interface function name: mouse-if
• protocol: Human Interface Device (HID)
• driver type (Windows): class ==> host support built in
• interface count: 1

​

Interface 1

• interface function name: tty-if
• protocol: CDC-ACM (serial)
• driver type (Windows): vendor ==> needs host config
• interface count 2

​

www.belcarra.com

Configuration 2: Interface 1

Interface 1 of Configuration 2 is ACM

• Microsoft offers USBSER.sys as a vendor ACM driver
• The ACM driver in the host OS must offer a match based on the following three values in addition to regular matching rules for the driver
• Vendor ID of Configuration 2
• Product ID of Configuration 2
• firstInterface 1

Notes:

• By default a different Product ID or a different interface will be seen by the host OS a distinct device.
• This is commonly used to create distinct host USB serial ports for different purposes.

www.belcarra.com

Configuration 3: hid-eem

Interface functions: mouse-if:eem-if

Interface 0

• interface function name: mouse-if
• protocol: Human Interface Device (HID)
• driver type (Windows): class ==> host support built in
• interface count: 1

Interface 1

• interface function name: eem-if
• protocol: CDC-EEM
• driver type (Windows): vendor ==> needs host config
• interface count 1

www.belcarra.com

Configuration 3: Interface 1

Interface 1 of Configuration 3 is EEM

• EEM needs a vendor driver such as Belcarra USBLAN
• The EEM vendor driver in the host OS must offer a match based on the following three values in addition to regular matching rules for the driver
• Vendor ID of Configuration 2
• Product ID of Configuration 2
• firstInterface 1

Notes:

• The interface list "eem-if:mouse-if" would not be matched (another rule could be added)
• The Product ID cannot be the same as Configuration 2. Otherwise there would be a potential conflict between the USBLAN and the serial driver

Composite Configuration: details

A new composite configuration will have the following minimum details (with values from Configuration 3).

• composite_function.driver.name = "hid-eem"
• interface_functions = "mouse-if:eem-if"
• bDeviceClass = USB_CLASS_MISC
• iConfiguration = "hid-eem"
• VendorID
• ProductID

​

Some details follow

​

​

www.belcarra.com

Configuration fields - Part 1

composite_function.driver.name = "hid-eem"

This is the name used by generic_cf to refer to the configuration internally

iConfiguration = "hid-eem"

this name is placed in the Configuration Desciptor. This name is visible by use of tools such as USBVIEW but is not used by the host for device identification.

bDeviceClass = USB_CLASS_MISC

This symbolic value = 0EFh is prescribed for all IAD (composite) configurations.

Belcarra automatically inserts matching required bDeviceSubclass and bDeviceProtocol values.

Configuration fields - Part 2

​

VendorID

Standard VendorID value issued by usb.org. For test purposes only, Belcarra's Vendor ID 15ec can be used.

​

ProductID

Product ID value issued by device manufacturer. Belcarra issues demo versions of its USBLAN driver with Vendor ID 15ec (Belcarra) and specified Product ID

http://usblan.belcarra.com/

IAD Descriptor details

IAD Descriptors contain fields of two types:

• Count and group interfaces for a subfunction
• Identify protocol of subfunction (this information is in the Device Descriptor of a single-function device)

Specifically, fields of the first type are:

• bFirstInterface -- index of the first interface of this function. This value for the first function is 0
• bInterfaceCount -- number of interfaces in this function. This value is: 1 for hid,msc,eem, blan; 2 for acm (serial), ecm

Fields of the second type: bFunctionClass, bFunctionSubClass, bFunctionProtocol.

The values for these fields are taken from similarly named fields in other descriptors for single-function devices

www.belcarra.com

Configuration 3, IAD Descriptors

IAD descriptors are generated automatically based on values from the interface functions

IAD0 values are from Function 0 : mouse-if

bFirstInterface:0

bInterfaceCount:1

bFunctionClass:3 (Human interface device)

bFunctionSubClass:1 (Boot interface subclass)

bFunctionProtocol:2 (Mouse)

IAD1 uses values from Function 1: eem-if

bFirstInterface:1

bInterfaceCount:1

bFunctionClass:2 (Communications class code)

bFunctionSubClass:0C (EEM Subclass code)

bFunctionProtocol:07 (EEM protocol code)

I

www.belcarra.com

Interface functions

• Interface functions implement the low-level (data transport) parts of popular USB functions
• CDC-ACM (serial)
• MSC (mass storage, bulk-only)
• HID (mouse) -- random mouse, useful for test purposes
• the network_if component implements several different network protocols, such as
• CDC-ECM (aka CDC Ethernet)
• CDC-EEM
• CDC-BLAN (also known a MDLM BLAN)
• 1 or more instances of interface functions are used to create a composite configuration

www.belcarra.com

Interface Function Instances

For each interface function named in a composite configuration, the Belcarra USB system creates functionally separate interface instances via the interface_names parameter

• the module tty_if allows the interface function tty-if to be named in a composite configuration.
• interface_names="tty_if" -- provides a single serial port
• interface_names="tty_if:tty_if" -- provides 2 serial ports
• the module network_if allows one instance of any of various specific network protocols, for instance:
• interface_names="ecm" -- CDC-ECM
• interface_names="eem" -- CDC-EEM
• the module mouse_if allows one or more instances of "mouse-if"

www.belcarra.com

Vendor composite framework

Belcarra's generic_cf has two roles

• A storehouse of predefined composite configurations
• A model for a customer-created composite_framework

For a final product product, the generic_cf should be cloned and adapted to specific needs

• Only selected composite combination needed for field use are included
• Vendor and Product ID values are preset according to target device needs, and all Belcarra 15ec combinations are removed
• The predefined configuration list is extended

The new module vendor_cf should be used instead

​

www.belcarra.com

USB target milestones

• Test with the predefined configurations in vendor_cf carried over from generic_cf
• Verify new composite combinations created in vendor_cf.
• New function will use the target device Vendor and Product ID values
• A small useful subset of the functions in generic_cf will be copied
• New configuration combinations not found in generic_cf need to be created.

www.belcarra.com

USB host milestones

Host side -- repeated for each supported Host OS

• Vendor or class drivers for each function
• Installing a vendor driver that matches each VID/PID/MI combination in all functions of all supported configurations
• Ensure that there are no duplicate matches (more than 1 driver matching a VID/PID/MI combination

​

Note: IAD concept of firstInterface is mapped to the earlier/legacy host concept of matching interface # (MI)

www.belcarra.com

Example of possible matching conflicts

In each example we give the list of interface drivers, then the firstInterface values, and comments

1. mouse-if:tty-if 0/1 ACM driver must match MI_1

2. mouse-if:eem-if 0/1 EEM driver must match MI_1. This configuration must use a different PID to avoid conflict

3. eem-if:mouse-if EEM driver must match MI_0. No conflict with Example 1 because HID is a class driver

4. tty-if:tty-if ACM driver(s) must match MI_0 and MI_2. Conflicts with Example 3. Compatible with Examples 1

& 2

5. tty-if:tty-if:eem-if Extends Example 4. EEM must match MI_4. EEM host driver must not match MI_0 or MI_2

6. msc-if:eem-if:tty-if Compatible with Example 4 and 5 (if EEM also matches MI-1). Conflicts with Example 1

www.belcarra.com