From dc42c5eb6b663b0b117b5660ba5818186744efd5 Mon Sep 17 00:00:00 2001
From: Dean Camera <dean@fourwalledcubicle.com>
Date: Thu, 4 Jun 2009 04:02:55 +0000
Subject: [PATCH] Added Doxygen documentation to the Audio class driver. Added
new modules for each of the new device class drivers to the library
documentation.
---
LUFA/ChangeLog.txt | 3 +-
LUFA/DirectorySummaries.txt | 10 +
LUFA/Drivers/USB/Class/Device/Audio.h | 202 ++++++++++++++++++--
LUFA/Drivers/USB/Class/Device/CDC.h | 16 ++
LUFA/Drivers/USB/Class/Device/HID.h | 16 ++
LUFA/Drivers/USB/Class/Device/MIDI.h | 17 ++
LUFA/Drivers/USB/Class/Device/MassStorage.h | 16 ++
LUFA/Drivers/USB/Class/Device/RNDIS.h | 16 ++
LUFA/Drivers/USB/USB.h | 27 +++
LUFA/Groups.txt | 2 +-
10 files changed, 306 insertions(+), 19 deletions(-)
diff --git a/LUFA/ChangeLog.txt b/LUFA/ChangeLog.txt
index 529cac40c..8c142532e 100644
--- a/LUFA/ChangeLog.txt
+++ b/LUFA/ChangeLog.txt
@@ -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
============================
diff --git a/LUFA/DirectorySummaries.txt b/LUFA/DirectorySummaries.txt
index 3fae9c18e..13cdc3e53 100644
--- a/LUFA/DirectorySummaries.txt
+++ b/LUFA/DirectorySummaries.txt
@@ -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.
*
diff --git a/LUFA/Drivers/USB/Class/Device/Audio.h b/LUFA/Drivers/USB/Class/Device/Audio.h
index f92b9ab91..cbb6d791b 100644
--- a/LUFA/Drivers/USB/Class/Device/Audio.h
+++ b/LUFA/Drivers/USB/Class/Device/Audio.h
@@ -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
+
+/** @} */
diff --git a/LUFA/Drivers/USB/Class/Device/CDC.h b/LUFA/Drivers/USB/Class/Device/CDC.h
index b1d7c6dda..ae069fafa 100644
--- a/LUFA/Drivers/USB/Class/Device/CDC.h
+++ b/LUFA/Drivers/USB/Class/Device/CDC.h
@@ -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
+
+/** @} */
diff --git a/LUFA/Drivers/USB/Class/Device/HID.h b/LUFA/Drivers/USB/Class/Device/HID.h
index 9a2f803a4..9a563040c 100644
--- a/LUFA/Drivers/USB/Class/Device/HID.h
+++ b/LUFA/Drivers/USB/Class/Device/HID.h
@@ -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
+
+/** @} */
diff --git a/LUFA/Drivers/USB/Class/Device/MIDI.h b/LUFA/Drivers/USB/Class/Device/MIDI.h
index d15872263..b2294d86c 100644
--- a/LUFA/Drivers/USB/Class/Device/MIDI.h
+++ b/LUFA/Drivers/USB/Class/Device/MIDI.h
@@ -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
+
+/** @} */
diff --git a/LUFA/Drivers/USB/Class/Device/MassStorage.h b/LUFA/Drivers/USB/Class/Device/MassStorage.h
index cf2b5749a..d8da15c2b 100644
--- a/LUFA/Drivers/USB/Class/Device/MassStorage.h
+++ b/LUFA/Drivers/USB/Class/Device/MassStorage.h
@@ -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
+
+/** @} */
diff --git a/LUFA/Drivers/USB/Class/Device/RNDIS.h b/LUFA/Drivers/USB/Class/Device/RNDIS.h
index 09d48c31e..a8c8db9b7 100644
--- a/LUFA/Drivers/USB/Class/Device/RNDIS.h
+++ b/LUFA/Drivers/USB/Class/Device/RNDIS.h
@@ -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
+
+/** @} */
diff --git a/LUFA/Drivers/USB/USB.h b/LUFA/Drivers/USB/USB.h
index 3c8f06237..d0837a844 100644
--- a/LUFA/Drivers/USB/USB.h
+++ b/LUFA/Drivers/USB/USB.h
@@ -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__
diff --git a/LUFA/Groups.txt b/LUFA/Groups.txt
index f479b51db..530ce28b4 100644
--- a/LUFA/Groups.txt
+++ b/LUFA/Groups.txt
@@ -17,4 +17,4 @@
/** @defgroup Group_MiscDrivers Miscellaneous Drivers
*
* Miscellaneous driver Functions, macros, variables, enums and types.
- */
\ No newline at end of file
+ */
--
GitLab