Conversion of old incomplete SideShow demo to new APIs.

[pub/USBasp.git] / LUFA / Drivers / USB / Class / Device / Audio.h

diff --git a/LUFA/Drivers/USB/Class/Device/Audio.h b/LUFA/Drivers/USB/Class/Device/Audio.h
index f92b9ab..230da4d 100644 (file)
--- a/LUFA/Drivers/USB/Class/Device/Audio.h
+++ b/LUFA/Drivers/USB/Class/Device/Audio.h
@@ -28,6 +28,20 @@
   this software.\r
 */\r
 \r
   this software.\r
 */\r
 \r

+/** \ingroup Group_USBDeviceClassDrivers\r
+ *  @defgroup Group_USBClassAudioDevice Audio Device Class Driver - LUFA/Drivers/Class/Device/Audio.h\r
+ *\r
+ *  \section Sec_Dependencies Module Source Dependencies\r
+ *  The following files must be built with any user project that uses this module:\r
+ *    - LUFA/Drivers/USB/Class/Device/Audio.c\r
+ *\r
+ *  \section Module Description\r
+ *  Functions, macros, variables, enums and types related to the management of USB Audio Class interfaces\r
+ *  within a USB device.\r
+ *\r
+ *  @{\r
+ */\r
+\r

 #ifndef _AUDIO_CLASS_H_\r
 #define _AUDIO_CLASS_H_\r
 \r
 #ifndef _AUDIO_CLASS_H_\r
 #define _AUDIO_CLASS_H_\r
 \r


@@ -66,60 +80,127 @@
                /** Audio class descriptor subtype value for an Audio class specific descriptor indicating the format of an audio stream. */\r
                #define DSUBTYPE_Format              0x02\r
                \r
                /** Audio class descriptor subtype value for an Audio class specific descriptor indicating the format of an audio stream. */\r
                #define DSUBTYPE_Format              0x02\r
                \r

-               //@{\r

                /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r
                /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

-\r

                #define CHANNEL_LEFT_FRONT           (1 << 0)\r
                #define CHANNEL_LEFT_FRONT           (1 << 0)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_RIGHT_FRONT          (1 << 1)\r
                #define CHANNEL_RIGHT_FRONT          (1 << 1)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_CENTER_FRONT         (1 << 2)\r
                #define CHANNEL_CENTER_FRONT         (1 << 2)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_LOW_FREQ_ENHANCE     (1 << 3)\r
                #define CHANNEL_LOW_FREQ_ENHANCE     (1 << 3)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_LEFT_SURROUND        (1 << 4)\r
                #define CHANNEL_LEFT_SURROUND        (1 << 4)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_RIGHT_SURROUND       (1 << 5)\r
                #define CHANNEL_RIGHT_SURROUND       (1 << 5)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_LEFT_OF_CENTER       (1 << 6)\r
                #define CHANNEL_LEFT_OF_CENTER       (1 << 6)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_RIGHT_OF_CENTER      (1 << 7)\r
                #define CHANNEL_RIGHT_OF_CENTER      (1 << 7)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_SURROUND             (1 << 8)\r
                #define CHANNEL_SURROUND             (1 << 8)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_SIDE_LEFT            (1 << 9)\r
                #define CHANNEL_SIDE_LEFT            (1 << 9)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_SIDE_RIGHT           (1 << 10)\r
                #define CHANNEL_SIDE_RIGHT           (1 << 10)\r

+\r
+               /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */\r

                #define CHANNEL_TOP                  (1 << 11)\r
                #define CHANNEL_TOP                  (1 << 11)\r

-               //@}\r

 \r
 \r

-               //@{\r

                /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r
                /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

-\r

                #define FEATURE_MUTE                 (1 << 0)\r
                #define FEATURE_MUTE                 (1 << 0)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_VOLUME               (1 << 1)\r
                #define FEATURE_VOLUME               (1 << 1)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_BASS                 (1 << 2)\r
                #define FEATURE_BASS                 (1 << 2)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_MID                  (1 << 3)\r
                #define FEATURE_MID                  (1 << 3)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_TREBLE               (1 << 4)\r
                #define FEATURE_TREBLE               (1 << 4)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_GRAPHIC_EQUALIZER    (1 << 5)\r
                #define FEATURE_GRAPHIC_EQUALIZER    (1 << 5)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r
+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_AUTOMATIC_GAIN       (1 << 6)\r
                #define FEATURE_AUTOMATIC_GAIN       (1 << 6)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_DELAY                (1 << 7)\r
                #define FEATURE_DELAY                (1 << 7)\r

+\r
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_BASS_BOOST           (1 << 8)\r
                #define FEATURE_BASS_BOOST           (1 << 8)\r

+
+               /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */\r

                #define FEATURE_BASS_LOUDNESS        (1 << 9)\r
                #define FEATURE_BASS_LOUDNESS        (1 << 9)\r

-               //@}\r

 \r
 \r

-               //@{\r
-               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */\r
-               \r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_UNDEFINED           0x0100\r
                #define TERMINAL_UNDEFINED           0x0100\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_STREAMING           0x0101\r
                #define TERMINAL_STREAMING           0x0101\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_VENDOR              0x01FF\r
                #define TERMINAL_VENDOR              0x01FF\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_UNDEFINED        0x0200\r
                #define TERMINAL_IN_UNDEFINED        0x0200\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_MIC              0x0201\r
                #define TERMINAL_IN_MIC              0x0201\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_DESKTOP_MIC      0x0202\r
                #define TERMINAL_IN_DESKTOP_MIC      0x0202\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_PERSONAL_MIC     0x0203\r
                #define TERMINAL_IN_PERSONAL_MIC     0x0203\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_OMNIDIR_MIC      0x0204\r
                #define TERMINAL_IN_OMNIDIR_MIC      0x0204\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_MIC_ARRAY        0x0205\r
                #define TERMINAL_IN_MIC_ARRAY        0x0205\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_PROCESSING_MIC   0x0206\r
                #define TERMINAL_IN_PROCESSING_MIC   0x0206\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_IN_OUT_UNDEFINED    0x0300\r
                #define TERMINAL_IN_OUT_UNDEFINED    0x0300\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_SPEAKER         0x0301\r
                #define TERMINAL_OUT_SPEAKER         0x0301\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_HEADPHONES      0x0302\r
                #define TERMINAL_OUT_HEADPHONES      0x0302\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_HEAD_MOUNTED    0x0303\r
                #define TERMINAL_OUT_HEAD_MOUNTED    0x0303\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_DESKTOP         0x0304\r
                #define TERMINAL_OUT_DESKTOP         0x0304\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_ROOM            0x0305\r
                #define TERMINAL_OUT_ROOM            0x0305\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_COMMUNICATION   0x0306\r
                #define TERMINAL_OUT_COMMUNICATION   0x0306\r

+\r
+               /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */               \r

                #define TERMINAL_OUT_LOWFREQ         0x0307\r
                #define TERMINAL_OUT_LOWFREQ         0x0307\r

-               //@}\r

 \r
                /** Convenience macro, to fill a 24-bit AudioSampleFreq_t structure with the given sample rate as a 24-bit number.\r
                 *\r
 \r
                /** Convenience macro, to fill a 24-bit AudioSampleFreq_t structure with the given sample rate as a 24-bit number.\r
                 *\r


@@ -280,32 +361,119 @@
                        uint16_t                  LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */\r
                } USB_AudioStreamEndpoint_Spc_t;        \r
 \r
                        uint16_t                  LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */\r
                } USB_AudioStreamEndpoint_Spc_t;        \r
 \r

+               /** Type define for an Audio Class interface configuration and state structure. This structure should be used for each Audio\r
+                *  Class unit within the device, and passed (per-interface) to the Audio Class driver functions so that each Audio interface\r
+                *  has seperate state and configuration data and can be controlled seperately.\r
+                */\r

                typedef struct\r
                {\r
                typedef struct\r
                {\r

-                       uint8_t  StreamingInterfaceNumber;\r
+                       uint8_t  StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this structure controls */\r

 \r
 \r

-                       uint8_t  DataINEndpointNumber;\r
-                       uint16_t DataINEndpointSize;\r
+                       uint8_t  DataINEndpointNumber; /**< Endpoint number of the incomming Audio Streaming data, if available (zero if unused) */\r
+                       uint16_t DataINEndpointSize; /**< Size in bytes of the incomming Audio Streaming data endpoint, if available (zero if unused) */\r

 \r
 \r

-                       uint8_t  DataOUTEndpointNumber;\r
-                       uint16_t DataOUTEndpointSize;\r
+                       uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the outgoing Audio Streaming data, if available (zero if unused) */\r
+                       uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing Audio Streaming data endpoint, if available (zero if unused) */\r

 \r
 \r

-                       bool     InterfaceEnabled;\r
+                       bool     InterfaceEnabled; /**< Set and cleared by the class driver to indicate if the host has enabled the streaming endpoints\r
+                                                   *   of the Audio Streaming interface\r
+                                                   */\r

                } USB_ClassInfo_Audio_t;\r
                \r
        /* Function Prototypes: */\r
                } USB_ClassInfo_Audio_t;\r
                \r
        /* Function Prototypes: */\r

-               bool     USB_Audio_ConfigureEndpoints(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
-               void     USB_Audio_ProcessControlPacket(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
-               void     USB_Audio_USBTask(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
+               /** Configures the endpoints of a given Audio interface, ready for use. This should be linked to the library\r
+                *  \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration containing the\r
+                *  given Audio interface is selected.\r
+                *\r
+                *  \param AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.\r
+                *\r
+                *  \return Boolean true if the endpoints were sucessfully configured, false otherwise\r
+                */\r
+               bool USB_Audio_ConfigureEndpoints(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
+\r
+               /** Processes incomming control requests from the host, that are directed to the given Audio class interface. This should be\r
+                *  linked to the library \ref EVENT_USB_UnhandledControlPacket() event.\r
+                *\r
+                *  \param AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.\r
+                */\r
+               void USB_Audio_ProcessControlPacket(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
+\r
+               /** General management task for a given Audio class interface, required for the correct operation of the interface. This should\r
+                *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().\r
+                *\r
+                *  \param AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.\r
+                */\r
+               void USB_Audio_USBTask(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r

                \r
                \r

-               int8_t   USB_Audio_ReadSample8(void);\r
-               int16_t  USB_Audio_ReadSample16(void);\r
-               int32_t  USB_Audio_ReadSample24(void);\r
-               void     USB_Audio_WriteSample8(int8_t Sample);\r
-               void     USB_Audio_WriteSample16(int16_t Sample);\r
-               void     USB_Audio_WriteSample24(int32_t Sample);\r
-               bool     USB_Audio_IsSampleReceived(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
-               bool     USB_Audio_IsReadyForNextSample(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
+               /** Reads the next 8-bit audio sample from the current audio interface.\r
+                *\r
+                *  \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that\r
+                *        the correct endpoint is selected and ready for data.\r
+                *\r
+                *  \return  Signed 8-bit audio sample from the audio interface\r
+                */\r
+               int8_t USB_Audio_ReadSample8(void);\r
+\r
+               /** Reads the next 16-bit audio sample from the current audio interface.\r
+                *\r
+                *  \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that\r
+                *        the correct endpoint is selected and ready for data.\r
+                *\r
+                *  \return  Signed 16-bit audio sample from the audio interface\r
+                */\r
+               int16_t USB_Audio_ReadSample16(void);\r
+\r
+               /** Reads the next 24-bit audio sample from the current audio interface.\r
+                *\r
+                *  \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that\r
+                *        the correct endpoint is selected and ready for data.\r
+                *\r
+                *  \return  Signed 24-bit audio sample from the audio interface\r
+                */\r
+               int32_t USB_Audio_ReadSample24(void);\r
+\r
+               /** Writes the next 8-bit audio sample to the current audio interface.\r
+                *\r
+                *  \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that\r
+                *        the correct endpoint is selected and ready for data.\r
+                *\r
+                *  \param Sample  Signed 8-bit audio sample\r
+                */\r
+               void USB_Audio_WriteSample8(int8_t Sample);\r
+\r
+               /** Writes the next 16-bit audio sample to the current audio interface.\r
+                *\r
+                *  \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that\r
+                *        the correct endpoint is selected and ready for data.\r
+                *\r
+                *  \param Sample  Signed 16-bit audio sample\r
+                */\r
+               void USB_Audio_WriteSample16(int16_t Sample);\r
+\r
+               /** Writes the next 24-bit audio sample to the current audio interface.\r
+                *\r
+                *  \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that\r
+                *        the correct endpoint is selected and ready for data.\r
+                *\r
+                *  \param Sample  Signed 24-bit audio sample\r
+                */\r
+               void USB_Audio_WriteSample24(int32_t Sample);\r
+\r
+               /** Determines if the given audio interface is ready for a sample to be read from it.\r
+                *\r
+                *  \param AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.\r
+                *\r
+                *  \return Boolean true if the given Audio interface has a sample to be read, false otherwise\r
+                */\r
+               bool USB_Audio_IsSampleReceived(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r
+\r
+               /** Determines if the given audio interface is ready to accept the next sample to be written to it.\r
+                *\r
+                *  \param AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.\r
+                *\r
+                *  \return Boolean true if the given Audio interface is ready to accept the next sample, false otherwise\r
+                */\r
+               bool USB_Audio_IsReadyForNextSample(USB_ClassInfo_Audio_t* AudioInterfaceInfo);\r

 \r
        /* Disable C linkage for C++ Compilers: */\r
                #if defined(__cplusplus)\r
 \r
        /* Disable C linkage for C++ Compilers: */\r
                #if defined(__cplusplus)\r


@@ -313,3 +481,5 @@
                #endif\r
                \r
 #endif\r
                #endif\r
                \r
 #endif\r

+\r
+/** @} */\r