Commit a96d77ec authored by Dean Camera's avatar Dean Camera
Browse files

Add documentation to the USB Class Drivers module on how to use the Host mode class drivers.

parent 53eca61d
......@@ -235,7 +235,116 @@
* class-specific functions.
*
* \subsection SSec_ClassDriverHost Host Mode Class Drivers
* Implementing a Host Mode Class Driver in a user application requires a number of steps to be followed. Firstly,
* the module configuration and state structure must be added to the project source. These structures are named in a
* similar manner between classes, that of <i>USB_ClassInfo_<b>{Class Name}</b>_Host_t</i>, and are used to hold the
* complete state and configuration for each class instance. Multiple class instances is where the power of the class
* drivers lie; multiple interfaces of the same class simply require more instances of the Class Driver's ClassInfo
* structure.
*
* Inside the ClassInfo structure lies two sections, a <i>Config</i> section, and a <i>State</i> section. The Config
* section contains the instance's configuration parameters, and <b>must have all fields set by the user application</b>
* before the class driver is used. Each Device mode Class driver typically contains a set of configuration parameters
* for the endpoint size/number of the associated logical USB interface, plus any class-specific configuration parameters.
*
* The <i>State</i> section of the ClassInfo structures are designed to be controlled by the Class Drivers only for
* maintaining the Class Driver instance's state, and should not normally be set by the user application.
*
* The following is an example of a properly initialized instance of the MIDI Class Driver structure:
*
* \code
* USB_ClassInfo_MIDI_Host_t My_MIDI_Interface =
* {
* .Config =
* {
* .DataINPipeNumber = 1,
* .DataINPipeDoubleBank = false,
*
* .DataOUTPipeNumber = 2,
* .DataOUTPipeDoubleBank = false,
* },
* };
* \endcode
*
* To initialize the Class driver instance, the driver's <i><b>{Class Name}</b>_Host_ConfigurePipes()</i> function
* should be called in response to the host state machine entering the \ref HOST_STATE_Addressed state. This function
* will return an error code from the class driver's <i><b>{Class Name}</b>_EnumerationFailure_ErrorCodes_t</i> enum
* to indicate if the driver sucessfully initialized the instance and bound it to an interface in the attached device.
* Like all the class driver functions, this function takes in the address of the specific instance you wish to initialize
* - in this manner, multiple seperate instances of the same class type can be initialized. A fragment of a Class Driver
* based Host mode application may look like the following:
*
* \code
* switch (USB_HostState)
* {
* case HOST_STATE_Addressed:
* LEDs_SetAllLEDs(LEDMASK_USB_ENUMERATING);
*
* uint16_t ConfigDescriptorSize;
* uint8_t ConfigDescriptorData[512];
*
* if (USB_Host_GetDeviceConfigDescriptor(1, &ConfigDescriptorSize, ConfigDescriptorData,
* sizeof(ConfigDescriptorData)) != HOST_GETCONFIG_Successful)
* {
* LEDs_SetAllLEDs(LEDMASK_USB_ERROR);
* USB_HostState = HOST_STATE_WaitForDeviceRemoval;
* break;
* }
*
* if (MIDI_Host_ConfigurePipes(&My_MIDI_Interface,
* ConfigDescriptorSize, ConfigDescriptorData) != MIDI_ENUMERROR_NoError)
* {
* LEDs_SetAllLEDs(LEDMASK_USB_ERROR);
* USB_HostState = HOST_STATE_WaitForDeviceRemoval;
* break;
* }
*
* // Other state handler code here
* \endcode
*
* Note that the function also required the device's configuration descriptor so that it can determine which interface
* in the device to bind to - this can be retrieved as shown in the above fragment using the
* \ref USB_Host_GetDeviceConfigDescriptor() function. If the device does not implement the interface the class driver
* is looking for, if all the matching interfaces are already bound to class driver instances or if an error occurs while
* binding to a device interface (for example, a device endpoint bank larger that the maximum supported bank size is used)
* the configuration will fail.
*
* Once initialized, it is important to maintain the class driver's state by repeatedly calling the Class Driver's
* <i><b>{Class Name}</b>_Host_USBTask()</i> function in the main program loop. The exact implementation of this
* function varies between class drivers, and can be used for any internal class driver purpose to maintain each
* instance. Again, this function uses the address of the instance to operate on, and thus needs to be called for each
* seperate instance, just like the main USB maintenance routine \ref USB_USBTask():
*
* \code
* int main(void)
* {
* SetupHardware();
*
* LEDs_SetAllLEDs(LEDMASK_USB_NOTREADY);
*
* for (;;)
* {
* switch (USB_HostState)
* {
* // Host state machine handling here
* }
*
* MIDI_Host_USBTask(&My_Audio_Interface);
* USB_USBTask();
* }
* }
* \endcode
*
* Each class driver may also define a set of callback functions (which are prefixed by "CALLBACK_"
* in the function's name) which <b>must</b> also be added to the user application - refer to each
* individual class driver's documentation for mandatory callbacks. In addition, each class driver may
* also define a set of events (identifiable by their prefix of "EVENT_" in the function's name), which
* the user application <b>may</b> choose to implement, or ignore if not needed.
*
* The individual Host Mode Class Driver documentation contains more information on the non-standardized,
* class-specific functions which the user application can then use on the driver instances, such as data
* read and write routines. See each driver's individual documentation for more information on the
* class-specific functions.
*/
#ifndef __USB_H__
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment