Bluetooth demo can now create and maintain logical channels - need to determine why...

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

diff --git a/LUFA/Drivers/USB/Class/Common/Audio.h b/LUFA/Drivers/USB/Class/Common/Audio.h
index 07667a5..5127588 100644 (file)
--- a/LUFA/Drivers/USB/Class/Common/Audio.h
+++ b/LUFA/Drivers/USB/Class/Common/Audio.h
@@ -1,21 +1,21 @@
 /*\r
              LUFA Library\r
 /*\r
              LUFA Library\r

-     Copyright (C) Dean Camera, 2009.\r
+     Copyright (C) Dean Camera, 2010.\r

               \r
   dean [at] fourwalledcubicle [dot] com\r
       www.fourwalledcubicle.com\r
 */\r
 \r
 /*\r
               \r
   dean [at] fourwalledcubicle [dot] com\r
       www.fourwalledcubicle.com\r
 */\r
 \r
 /*\r

-  Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
-\r
-  Permission to use, copy, modify, and distribute this software\r
-  and its documentation for any purpose and without fee is hereby\r
-  granted, provided that the above copyright notice appear in all\r
-  copies and that both that the copyright notice and this\r
-  permission notice and warranty disclaimer appear in supporting\r
-  documentation, and that the name of the author not be used in\r
-  advertising or publicity pertaining to distribution of the\r
+  Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
+\r
+  Permission to use, copy, modify, distribute, and sell this \r
+  software and its documentation for any purpose is hereby granted\r
+  without fee, provided that the above copyright notice appear in \r
+  all copies and that both that the copyright notice and this\r
+  permission notice and warranty disclaimer appear in supporting \r
+  documentation, and that the name of the author not be used in \r
+  advertising or publicity pertaining to distribution of the \r

   software without specific, written prior permission.\r
 \r
   The author disclaim all warranties with regard to this\r
   software without specific, written prior permission.\r
 \r
   The author disclaim all warranties with regard to this\r


@@ -28,7 +28,22 @@
   this software.\r
 */\r
 \r
   this software.\r
 */\r
 \r

+/** \file\r
+ *  \brief Common definitions and declarations for the library USB Audio Class driver.\r
+ *\r
+ *  Common definitions and declarations for the library USB Audio Class driver.\r
+ *\r
+ *  \note This file should not be included directly. It is automatically included as needed by the class driver\r
+ *        dispatch header located in LUFA/Drivers/USB/Class/Audio.h.\r
+ */\r
+\r

 /** \ingroup Group_USBClassAudio\r
 /** \ingroup Group_USBClassAudio\r

+ *  @defgroup Group_USBClassAudioCommon  Common Class Definitions\r
+ *\r
+ *  \section Module Description\r
+ *  Constants, Types and Enum definitions that are common to both Device and Host modes for the USB\r
+ *  Audio Class.\r
+ *\r

  *  @{\r
  */\r
 \r
  *  @{\r
  */\r
 \r


@@ -45,7 +60,19 @@
                        extern "C" {\r
                #endif\r
 \r
                        extern "C" {\r
                #endif\r
 \r

+       /* Preprocessor Checks: */\r
+               #if !defined(__INCLUDE_FROM_AUDIO_DRIVER)\r
+                       #error Do not include this file directly. Include LUFA/Drivers/Class/Audio.h instead.\r
+               #endif\r
+\r

        /* Macros: */\r
        /* Macros: */\r

+               #if !defined(AUDIO_TOTAL_SAMPLE_RATES) || defined(__DOXYGEN__)\r
+                       /** Total number of discrete audio sample rates supported by the device. This value can be overridden by defining this\r
+                        *  token in the project makefile to the desired value, and passing it to the compiler via the -D switch.\r
+                        */\r
+                       #define AUDIO_TOTAL_SAMPLE_RATES    1\r
+               #endif\r
+               \r

                /** Descriptor header constant to indicate a Audio class interface descriptor. */\r
                #define DTYPE_AudioInterface         0x24\r
 \r
                /** Descriptor header constant to indicate a Audio class interface descriptor. */\r
                #define DTYPE_AudioInterface         0x24\r
 \r


@@ -134,7 +161,7 @@
 \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
 \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

-
+\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
 \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
 \r


@@ -194,7 +221,7 @@
 \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

-                *  \param freq  Required audio sampling frequency in HZ\r
+                *  \param[in] freq  Required audio sampling frequency in HZ\r

                 */\r
                #define AUDIO_SAMPLE_FREQ(freq)  {LowWord: ((uint32_t)freq & 0x00FFFF), HighByte: (((uint32_t)freq >> 16) & 0x0000FF)}\r
                \r
                 */\r
                #define AUDIO_SAMPLE_FREQ(freq)  {LowWord: ((uint32_t)freq & 0x00FFFF), HighByte: (((uint32_t)freq >> 16) & 0x0000FF)}\r
                \r


@@ -209,7 +236,9 @@
                #define EP_ACCEPTS_SMALL_PACKETS     (0 << 7)\r
                \r
        /* Type Defines: */\r
                #define EP_ACCEPTS_SMALL_PACKETS     (0 << 7)\r
                \r
        /* Type Defines: */\r

-               /** Type define for an Audio class specific interface descriptor. This follows a regular interface descriptor to\r
+               /** \brief Audio Class Specific Interface Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific interface descriptor. This follows a regular interface descriptor to\r

                 *  supply extra information about the audio device's layout to the host. See the USB Audio specification for more\r
                 *  details.\r
                 */\r
                 *  supply extra information about the audio device's layout to the host. See the USB Audio specification for more\r
                 *  details.\r
                 */\r


@@ -223,9 +252,11 @@
                        \r
                        uint8_t                   InCollection; /**< Total number of audio class interfaces within this device */\r
                        uint8_t                   InterfaceNumbers[1]; /**< Interface numbers of each audio interface */\r
                        \r
                        uint8_t                   InCollection; /**< Total number of audio class interfaces within this device */\r
                        uint8_t                   InterfaceNumbers[1]; /**< Interface numbers of each audio interface */\r

-               } USB_AudioInterface_AC_t;\r
+               } USB_Audio_Interface_AC_t;\r

                \r
                \r

-               /** Type define for an Audio class specific Feature Unit descriptor. This indicates to the host what features\r
+               /** \brief Audio Class Specific Feature Unit Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific Feature Unit descriptor. This indicates to the host what features\r

                 *  are present in the device's audio stream for basic control, such as per-channel volume. See the USB Audio\r
                 *  specification for more details.\r
                 */\r
                 *  are present in the device's audio stream for basic control, such as per-channel volume. See the USB Audio\r
                 *  specification for more details.\r
                 */\r


@@ -241,9 +272,11 @@
                        uint8_t                   ChannelControls[3]; /**< Feature masks for the control channel, and each separate audio channel */\r
                        \r
                        uint8_t                   FeatureUnitStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                        uint8_t                   ChannelControls[3]; /**< Feature masks for the control channel, and each separate audio channel */\r
                        \r
                        uint8_t                   FeatureUnitStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r

-               } USB_AudioFeatureUnit_t;\r
+               } USB_Audio_FeatureUnit_t;\r

 \r
 \r

-               /** Type define for an Audio class specific input terminal descriptor. This indicates to the host that the device\r
+               /** \brief Audio Class Specific Input Terminal Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific input terminal descriptor. This indicates to the host that the device\r

                 *  contains an input audio source, either from a physical terminal on the device, or a logical terminal (for example,\r
                 *  a USB endpoint). See the USB Audio specification for more details.\r
                 */\r
                 *  contains an input audio source, either from a physical terminal on the device, or a logical terminal (for example,\r
                 *  a USB endpoint). See the USB Audio specification for more details.\r
                 */\r


@@ -262,9 +295,11 @@
                        \r
                        uint8_t                   ChannelStrIndex; /**< Index of a string descriptor describing this channel within the device */\r
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                        \r
                        uint8_t                   ChannelStrIndex; /**< Index of a string descriptor describing this channel within the device */\r
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r

-               } USB_AudioInputTerminal_t;\r
+               } USB_Audio_InputTerminal_t;\r

 \r
 \r

-               /** Type define for an Audio class specific output terminal descriptor. This indicates to the host that the device\r
+               /** \brief Audio Class Specific Output Terminal Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific output terminal descriptor. This indicates to the host that the device\r

                 *  contains an output audio sink, either to a physical terminal on the device, or a logical terminal (for example,\r
                 *  a USB endpoint). See the USB Audio specification for more details.\r
                 */\r
                 *  contains an output audio sink, either to a physical terminal on the device, or a logical terminal (for example,\r
                 *  a USB endpoint). See the USB Audio specification for more details.\r
                 */\r


@@ -281,9 +316,11 @@
                        uint8_t                   SourceID; /**< ID value of the unit this terminal's audio is sourced from */\r
                        \r
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                        uint8_t                   SourceID; /**< ID value of the unit this terminal's audio is sourced from */\r
                        \r
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r

-               } USB_AudioOutputTerminal_t;\r
+               } USB_Audio_OutputTerminal_t;\r

                \r
                \r

-               /** Type define for an Audio class specific streaming interface descriptor. This indicates to the host\r
+               /** \brief Audio Class Specific Streaming Audio Interface Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific streaming interface descriptor. This indicates to the host\r

                 *  how audio streams within the device are formatted. See the USB Audio specification for more details.\r
                 */\r
                typedef struct\r
                 *  how audio streams within the device are formatted. See the USB Audio specification for more details.\r
                 */\r
                typedef struct\r


@@ -295,18 +332,22 @@
                        \r
                        uint8_t                   FrameDelay; /**< Delay in frames resulting from the complete sample processing from input to output */\r
                        uint16_t                  AudioFormat; /**< Format of the audio stream, see Audio Device Formats specification */\r
                        \r
                        uint8_t                   FrameDelay; /**< Delay in frames resulting from the complete sample processing from input to output */\r
                        uint16_t                  AudioFormat; /**< Format of the audio stream, see Audio Device Formats specification */\r

-               } USB_AudioInterface_AS_t;\r
+               } USB_Audio_Interface_AS_t;\r

                \r
                \r

-               /** Type define for a 24bit audio sample frequency structure. GCC does not contain a built in 24bit datatype,\r
+               /** \brief 24-Bit Audio Frequency Structure.\r
+                *\r
+                *  Type define for a 24bit audio sample frequency structure. GCC does not contain a built in 24bit datatype,\r

                 *  this this structure is used to build up the value instead. Fill this structure with the SAMPLE_FREQ() macro.\r
                 */\r
                typedef struct\r
                {\r
                        uint16_t                  LowWord; /**< Low 16 bits of the 24-bit value */\r
                        uint8_t                   HighByte; /**< Upper 8 bits of the 24-bit value */\r
                 *  this this structure is used to build up the value instead. Fill this structure with the SAMPLE_FREQ() macro.\r
                 */\r
                typedef struct\r
                {\r
                        uint16_t                  LowWord; /**< Low 16 bits of the 24-bit value */\r
                        uint8_t                   HighByte; /**< Upper 8 bits of the 24-bit value */\r

-               } AudioSampleFreq_t;\r
+               } USB_Audio_SampleFreq_t;\r

 \r
 \r

-               /** Type define for an Audio class specific audio format descriptor. This is used to give the host full details\r
+               /** \brief Audio Class Specific Format Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific audio format descriptor. This is used to give the host full details\r

                 *  about the number of channels, the sample resolution, acceptable sample frequencies and encoding method used\r
                 *  in the device's audio streams. See the USB Audio specification for more details.\r
                 */\r
                 *  about the number of channels, the sample resolution, acceptable sample frequencies and encoding method used\r
                 *  in the device's audio streams. See the USB Audio specification for more details.\r
                 */\r


@@ -322,10 +363,12 @@
                        uint8_t                   BitResolution; /**< Bits of resolution of each channel's samples in the stream */\r
 \r
                        uint8_t                   SampleFrequencyType; /**< Total number of sample frequencies supported by the device */                       \r
                        uint8_t                   BitResolution; /**< Bits of resolution of each channel's samples in the stream */\r
 \r
                        uint8_t                   SampleFrequencyType; /**< Total number of sample frequencies supported by the device */                       \r

-                       AudioSampleFreq_t         SampleFrequencies[1]; /**< Sample frequencies supported by the device */\r
-               } USB_AudioFormat_t;\r
+                       USB_Audio_SampleFreq_t    SampleFrequencies[AUDIO_TOTAL_SAMPLE_RATES]; /**< Sample frequencies supported by the device */\r
+               } USB_Audio_Format_t;\r

                \r
                \r

-               /** Type define for an Audio class specific endpoint descriptor. This contains a regular endpoint \r
+               /** \brief Audio Class Specific Streaming Endpoint Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific endpoint descriptor. This contains a regular endpoint \r

                 *  descriptor with a few Audio-class specific extensions. See the USB Audio specification for more details.\r
                 */\r
                typedef struct\r
                 *  descriptor with a few Audio-class specific extensions. See the USB Audio specification for more details.\r
                 */\r
                typedef struct\r


@@ -333,10 +376,12 @@
                        USB_Descriptor_Endpoint_t Endpoint; /**< Standard endpoint descriptor describing the audio endpoint */\r
 \r
                        uint8_t                   Refresh; /**< Always set to zero */\r
                        USB_Descriptor_Endpoint_t Endpoint; /**< Standard endpoint descriptor describing the audio endpoint */\r
 \r
                        uint8_t                   Refresh; /**< Always set to zero */\r

-                       uint8_t                   SyncEndpointNumber; /**< Endpoint address to send synchronisation information to, if needed (zero otherwise) */\r
-               } USB_AudioStreamEndpoint_Std_t;\r
+                       uint8_t                   SyncEndpointNumber; /**< Endpoint address to send synchronization information to, if needed (zero otherwise) */\r
+               } USB_Audio_StreamEndpoint_Std_t;\r

                                        \r
                                        \r

-               /** Type define for an Audio class specific extended endpoint descriptor. This contains extra information\r
+               /** \brief Audio Class Specific Extended Endpoint Descriptor.\r
+                *\r
+                *  Type define for an Audio class specific extended endpoint descriptor. This contains extra information\r

                 *  on the usage of endpoints used to stream audio in and out of the USB Audio device, and follows an Audio\r
                 *  class specific extended endpoint descriptor. See the USB Audio specification for more details.\r
                 */\r
                 *  on the usage of endpoints used to stream audio in and out of the USB Audio device, and follows an Audio\r
                 *  class specific extended endpoint descriptor. See the USB Audio specification for more details.\r
                 */\r


@@ -349,7 +394,7 @@
 \r
                        uint8_t                   LockDelayUnits; /**< Units used for the LockDelay field, see Audio class specification */\r
                        uint16_t                  LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */\r
 \r
                        uint8_t                   LockDelayUnits; /**< Units used for the LockDelay field, see Audio class specification */\r
                        uint16_t                  LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */\r

-               } USB_AudioStreamEndpoint_Spc_t;\r
+               } USB_Audio_StreamEndpoint_Spc_t;\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