Added Doxygen documentation to the Audio class driver. Added new modules for each of the new device class drivers to the library documentation.

pull/1469/head
Dean Camera 16 years ago
parent d37d419ffa
commit dc42c5eb6b

@ -5,9 +5,8 @@
*/
========== TODO: ===========
- Document new class drivers
- Document new class drivers (in progress)
- Add standardized descriptor names to class driver structures, controlled by USE_NONSTANDARD_DESCRIPTOR_NAMES
- Disable JTAG in demos
- Convert Host mode demos to class drivers
- Remake AVRStudio projects to reflect file structure changes
============================

@ -61,6 +61,16 @@
* but provide a standard and library-maintained way of implementing functionality from some of the defined USB classes without extensive
* development effort. Is is recommended that these drivers be used where possible to reduce maintenance of user applications.
*
* \dir Drivers/USB/Class/Device
* \brief USB Device Class helper driver files.
*
* Device mode drivers for the standard USB classes.
*
* \dir Drivers/USB/Class/Host
* \brief USB Host Class helper driver files.
*
* Host mode drivers for the standard USB classes.
*
* \dir Drivers/Board
* \brief Board hardware driver files.
*

@ -28,6 +28,20 @@
this software.
*/
/** \ingroup Group_USBDeviceClassDrivers
* @defgroup Group_USBClassAudioDevice Audio Device Class Driver - LUFA/Drivers/Class/Device/Audio.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/Audio.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB Audio Class interfaces
* within a USB device.
*
* @{
*/
#ifndef _AUDIO_CLASS_H_
#define _AUDIO_CLASS_H_
@ -66,60 +80,127 @@
/** Audio class descriptor subtype value for an Audio class specific descriptor indicating the format of an audio stream. */
#define DSUBTYPE_Format 0x02
//@{
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_LEFT_FRONT (1 << 0)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_RIGHT_FRONT (1 << 1)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_CENTER_FRONT (1 << 2)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_LOW_FREQ_ENHANCE (1 << 3)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_LEFT_SURROUND (1 << 4)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_RIGHT_SURROUND (1 << 5)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_LEFT_OF_CENTER (1 << 6)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_RIGHT_OF_CENTER (1 << 7)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_SURROUND (1 << 8)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_SIDE_LEFT (1 << 9)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_SIDE_RIGHT (1 << 10)
/** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define CHANNEL_TOP (1 << 11)
//@}
//@{
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_MUTE (1 << 0)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_VOLUME (1 << 1)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_BASS (1 << 2)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_MID (1 << 3)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_TREBLE (1 << 4)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_GRAPHIC_EQUALIZER (1 << 5)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_AUTOMATIC_GAIN (1 << 6)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_DELAY (1 << 7)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_BASS_BOOST (1 << 8)
/** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */
#define FEATURE_BASS_LOUDNESS (1 << 9)
//@}
//@{
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_UNDEFINED 0x0100
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_STREAMING 0x0101
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_VENDOR 0x01FF
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_UNDEFINED 0x0200
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_MIC 0x0201
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_DESKTOP_MIC 0x0202
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_PERSONAL_MIC 0x0203
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_OMNIDIR_MIC 0x0204
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_MIC_ARRAY 0x0205
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_PROCESSING_MIC 0x0206
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_IN_OUT_UNDEFINED 0x0300
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_SPEAKER 0x0301
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_HEADPHONES 0x0302
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_HEAD_MOUNTED 0x0303
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_DESKTOP 0x0304
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_ROOM 0x0305
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_COMMUNICATION 0x0306
/** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */
#define TERMINAL_OUT_LOWFREQ 0x0307
//@}
/** Convenience macro, to fill a 24-bit AudioSampleFreq_t structure with the given sample rate as a 24-bit number.
*
@ -280,31 +361,118 @@
uint16_t LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */
} USB_AudioStreamEndpoint_Spc_t;
/** Type define for an Audio Class interface configuration and state structure. This structure should be used for each Audio
* Class unit within the device, and passed (per-interface) to the Audio Class driver functions so that each Audio interface
* has seperate state and configuration data and can be controlled seperately.
*/
typedef struct
{
uint8_t StreamingInterfaceNumber;
uint8_t StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this structure controls */
uint8_t DataINEndpointNumber;
uint16_t DataINEndpointSize;
uint8_t DataINEndpointNumber; /**< Endpoint number of the incomming Audio Streaming data, if available (zero if unused) */
uint16_t DataINEndpointSize; /**< Size in bytes of the incomming Audio Streaming data endpoint, if available (zero if unused) */
uint8_t DataOUTEndpointNumber;
uint16_t DataOUTEndpointSize;
uint8_t DataOUTEndpointNumber; /**< Endpoint number of the outgoing Audio Streaming data, if available (zero if unused) */
uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing Audio Streaming data endpoint, if available (zero if unused) */
bool InterfaceEnabled;
bool InterfaceEnabled; /**< Set and cleared by the class driver to indicate if the host has enabled the streaming endpoints
* of the Audio Streaming interface
*/
} USB_ClassInfo_Audio_t;
/* Function Prototypes: */
/** Configures the endpoints of a given Audio interface, ready for use. This should be linked to the library
* \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration containing the
* given Audio interface is selected.
*
* \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
*
* \return Boolean true if the endpoints were sucessfully configured, false otherwise
*/
bool USB_Audio_ConfigureEndpoints(USB_ClassInfo_Audio_t* AudioInterfaceInfo);
/** Processes incomming control requests from the host, that are directed to the given Audio class interface. This should be
* linked to the library \ref EVENT_USB_UnhandledControlPacket() event.
*
* \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
*/
void USB_Audio_ProcessControlPacket(USB_ClassInfo_Audio_t* AudioInterfaceInfo);
/** General management task for a given Audio class interface, required for the correct operation of the interface. This should
* be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
*
* \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
*/
void USB_Audio_USBTask(USB_ClassInfo_Audio_t* AudioInterfaceInfo);
/** Reads the next 8-bit audio sample from the current audio interface.
*
* \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
* the correct endpoint is selected and ready for data.
*
* \return Signed 8-bit audio sample from the audio interface
*/
int8_t USB_Audio_ReadSample8(void);
/** Reads the next 16-bit audio sample from the current audio interface.
*
* \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
* the correct endpoint is selected and ready for data.
*
* \return Signed 16-bit audio sample from the audio interface
*/
int16_t USB_Audio_ReadSample16(void);
/** Reads the next 24-bit audio sample from the current audio interface.
*
* \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
* the correct endpoint is selected and ready for data.
*
* \return Signed 24-bit audio sample from the audio interface
*/
int32_t USB_Audio_ReadSample24(void);
/** Writes the next 8-bit audio sample to the current audio interface.
*
* \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
* the correct endpoint is selected and ready for data.
*
* \param Sample Signed 8-bit audio sample
*/
void USB_Audio_WriteSample8(int8_t Sample);
/** Writes the next 16-bit audio sample to the current audio interface.
*
* \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
* the correct endpoint is selected and ready for data.
*
* \param Sample Signed 16-bit audio sample
*/
void USB_Audio_WriteSample16(int16_t Sample);
/** Writes the next 24-bit audio sample to the current audio interface.
*
* \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
* the correct endpoint is selected and ready for data.
*
* \param Sample Signed 24-bit audio sample
*/
void USB_Audio_WriteSample24(int32_t Sample);
/** Determines if the given audio interface is ready for a sample to be read from it.
*
* \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
*
* \return Boolean true if the given Audio interface has a sample to be read, false otherwise
*/
bool USB_Audio_IsSampleReceived(USB_ClassInfo_Audio_t* AudioInterfaceInfo);
/** Determines if the given audio interface is ready to accept the next sample to be written to it.
*
* \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
*
* \return Boolean true if the given Audio interface is ready to accept the next sample, false otherwise
*/
bool USB_Audio_IsReadyForNextSample(USB_ClassInfo_Audio_t* AudioInterfaceInfo);
/* Disable C linkage for C++ Compilers: */
@ -313,3 +481,5 @@
#endif
#endif
/** @} */

@ -28,6 +28,20 @@
this software.
*/
/** \ingroup Group_USBDeviceClassDrivers
* @defgroup Group_USBClassCDCDevice CDC Device Class Driver - LUFA/Drivers/Class/Device/CDC.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/CDC.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB CDC Class interfaces
* within a USB device, for the implementation of CDC-ACM virtual serial ports.
*
* @{
*/
#ifndef _CDC_CLASS_H_
#define _CDC_CLASS_H_
@ -195,3 +209,5 @@
#endif
#endif
/** @} */

@ -28,6 +28,20 @@
this software.
*/
/** \ingroup Group_USBDeviceClassDrivers
* @defgroup Group_USBClassHIDDevice HID Device Class Driver - LUFA/Drivers/Class/Device/HID.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/HID.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB HID Class interfaces
* within a USB device.
*
* @{
*/
#ifndef _HID_CLASS_H_
#define _HID_CLASS_H_
@ -122,3 +136,5 @@
#endif
#endif
/** @} */

@ -28,6 +28,21 @@
this software.
*/
/** \ingroup Group_USBDeviceClassDrivers
* @defgroup Group_USBClassMIDIDevice MIDI Device Class Driver - LUFA/Drivers/Class/Device/MIDI.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/MIDI.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB MIDI Class interfaces
* within a USB device. Note that the MIDI class is actually a special case of the regular Audio class,
* thus this module depends on structure definitions from the \ref Group_USBClassAudioDevice class driver module.
*
* @{
*/
#ifndef _MIDI_CLASS_H_
#define _MIDI_CLASS_H_
@ -167,3 +182,5 @@
#endif
#endif
/** @} */

@ -28,6 +28,20 @@
this software.
*/
/** \ingroup Group_USBDeviceClassDrivers
* @defgroup Group_USBClassMSDevice Mass Storage Device Class Driver - LUFA/Drivers/Class/Device/MassStorage.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/MassStorage.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB Mass Storage Class interfaces
* within a USB device.
*
* @{
*/
#ifndef _MS_CLASS_H_
#define _MS_CLASS_H_
@ -132,3 +146,5 @@
#endif
#endif
/** @} */

@ -28,6 +28,20 @@
this software.
*/
/** \ingroup Group_USBDeviceClassDrivers
* @defgroup Group_USBClassRNDISDevice RNDIS Device Class Driver - LUFA/Drivers/Class/Device/RNDIS.h
*
* \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module:
* - LUFA/Drivers/USB/Class/Device/HID.c
*
* \section Module Description
* Functions, macros, variables, enums and types related to the management of USB RNDIS Ethernet
* interfaces within a USB device.
*
* @{
*/
#ifndef _RNDIS_CLASS_H_
#define _RNDIS_CLASS_H_
@ -267,3 +281,5 @@
#endif
#endif
/** @} */

@ -54,6 +54,33 @@
* Functions, macros, variables, enums and types related to the management of USB communications.
*/
/** \ingroup Group_USB
* @defgroup Group_USBClassDrivers USB Class Drivers
*
* Drivers for both host and device mode of the standard USB classes, for rapid application development.
* Class drivers give a framework which sits on top of the low level library API, allowing for standard
* USB classes to be implemented in a project with minimal user code. These drivers can be used in
* conjunction with the library low level APIs to implement interfaces both via the class drivers and via
* the standard library APIs.
*
* Multiple device mode class drivers can be used within a project, including multiple instances of the
* same class driver.
*/
/** \ingroup Group_USBClassDrivers
* @defgroup Group_USBDeviceClassDrivers Device Class Drivers
*
* Device mode drivers for the standard USB classes. These drivers all implement one of the standard USB
* classes, allowing for the class to be easily implemented in a user project.
*/
/** \ingroup Group_USBClassDrivers
* @defgroup Group_USBHostClassDrivers Host Class Drivers
*
* Host mode drivers for the standard USB classes. These drivers all implement one of the standard USB
* classes, allowing for the class to be easily implemented in a user project.
*/
#ifndef __USB_H__
#define __USB_H__

@ -17,4 +17,4 @@
/** @defgroup Group_MiscDrivers Miscellaneous Drivers
*
* Miscellaneous driver Functions, macros, variables, enums and types.
*/
*/

Loading…
Cancel
Save