From a436fbb61266f6df03b4c50cd783592b7dad5029 Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Thu, 2 Feb 2012 20:17:22 +0000 Subject: [PATCH] Minor documentation improvements. --- LUFA/Drivers/USB/USB.h | 85 +++++++++++++++++++++++------------------- 1 file changed, 46 insertions(+), 39 deletions(-) diff --git a/LUFA/Drivers/USB/USB.h b/LUFA/Drivers/USB/USB.h index fa4955620a..692ffe77bd 100644 --- a/LUFA/Drivers/USB/USB.h +++ b/LUFA/Drivers/USB/USB.h @@ -158,8 +158,8 @@ * 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 \c State section of the \c USB_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. + * \note The \c State section of the \c USB_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 altered by the user application. * * The following is an example of a properly initialized instance of the Audio Class Driver structure: * @@ -188,10 +188,10 @@ * \code * void EVENT_USB_Device_ConfigurationChanged(void) * { - * LEDs_SetAllLEDs(LEDMASK_USB_READY); + * LEDs_SetAllLEDs(LEDMASK_USB_READY); * - * if (!(Audio_Device_ConfigureEndpoints(&My_Audio_Interface))) - * LEDs_SetAllLEDs(LEDMASK_USB_ERROR); + * if (!(Audio_Device_ConfigureEndpoints(&My_Audio_Interface))) + * LEDs_SetAllLEDs(LEDMASK_USB_ERROR); * } * \endcode * @@ -210,7 +210,8 @@ * * for (;;) * { - * Create_And_Process_Samples(); + * if (USB_DeviceState != DEVICE_STATE_Configured) + * Create_And_Process_Samples(); * * Audio_Device_USBTask(&My_Audio_Interface); * USB_USBTask(); @@ -257,10 +258,10 @@ * 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 \c State section of the \c USB_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. + * \note The \c State section of the \c USB_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 altered by the user application. * - * The following is an example of a properly initialized instance of the MIDI Class Driver structure: + * The following is an example of a properly initialized instance of the MIDI Host Class Driver structure: * * \code * USB_ClassInfo_MIDI_Host_t My_MIDI_Interface = @@ -277,7 +278,7 @@ * \endcode * * To initialize the Class driver instance, the driver's {Class Name}_Host_ConfigurePipes() function - * should be called in response to the host state machine entering the \ref HOST_STATE_Addressed state. This function + * should be called in response to the \c EVENT_USB_Host_DeviceEnumerationComplete() event firing. This function will * will return an error code from the class driver's {Class Name}_EnumerationFailure_ErrorCodes_t enum * to indicate if the driver successfully 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 - @@ -285,40 +286,48 @@ * based Host mode application may look like the following: * * \code - * switch (USB_HostState) + * void EVENT_USB_Host_DeviceEnumerationComplete(void) + * { + * 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); + * return; + * } + * + * if (MIDI_Host_ConfigurePipes(&Keyboard_MIDI_Interface, + * ConfigDescriptorSize, ConfigDescriptorData) != MIDI_ENUMERROR_NoError) + * { + * LEDs_SetAllLEDs(LEDMASK_USB_ERROR); + * return; + * } + * + * if (USB_Host_SetDeviceConfiguration(1) != HOST_SENDCONTROL_Successful) * { - * 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 + * LEDs_SetAllLEDs(LEDMASK_USB_ERROR); + * return; + * } + * + * LEDs_SetAllLEDs(LEDMASK_USB_READY); + * } * \endcode * - * Note that the function also required the device's configuration descriptor so that it can determine which interface + * Note that the function also requires 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. * + * To complete the device enumeration after binding the host mode Class Drivers to the attached device, a call to + * \c USB_Host_SetDeviceConfiguration() must be made. If the device configuration is not set within the + * \c EVENT_USB_Host_DeviceEnumerationComplete() event, the host still will assume the device enumeration has failed. + * * Once initialized, it is important to maintain the class driver's state by repeatedly calling the Class Driver's * {Class Name}_Host_USBTask() 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 @@ -334,10 +343,8 @@ * * for (;;) * { - * switch (USB_HostState) - * { - * // Host state machine handling here - * } + * if (USB_HostState != HOST_STATE_Configured) + * Create_And_Process_Samples(); * * MIDI_Host_USBTask(&My_Audio_Interface); * USB_USBTask();