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 2508daa..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,6 +28,15 @@
   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
  *  @defgroup Group_USBClassAudioCommon  Common Class Definitions\r
  *\r
 /** \ingroup Group_USBClassAudio\r
  *  @defgroup Group_USBClassAudioCommon  Common Class Definitions\r
  *\r


@@ -51,6 +60,11 @@
                        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
                #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
        /* 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


@@ -147,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


@@ -222,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


@@ -238,7 +254,9 @@
                        uint8_t                   InterfaceNumbers[1]; /**< Interface numbers of each audio interface */\r
                } USB_Audio_Interface_AC_t;\r
                \r
                        uint8_t                   InterfaceNumbers[1]; /**< Interface numbers of each audio interface */\r
                } USB_Audio_Interface_AC_t;\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


@@ -256,7 +274,9 @@
                        uint8_t                   FeatureUnitStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                } USB_Audio_FeatureUnit_t;\r
 \r
                        uint8_t                   FeatureUnitStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                } USB_Audio_FeatureUnit_t;\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


@@ -277,7 +297,9 @@
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                } USB_Audio_InputTerminal_t;\r
 \r
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                } USB_Audio_InputTerminal_t;\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


@@ -296,7 +318,9 @@
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                } USB_Audio_OutputTerminal_t;\r
                \r
                        uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */\r
                } USB_Audio_OutputTerminal_t;\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


@@ -310,7 +334,9 @@
                        uint16_t                  AudioFormat; /**< Format of the audio stream, see Audio Device Formats specification */\r
                } USB_Audio_Interface_AS_t;\r
                \r
                        uint16_t                  AudioFormat; /**< Format of the audio stream, see Audio Device Formats specification */\r
                } USB_Audio_Interface_AS_t;\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
                 *  this this structure is used to build up the value instead. Fill this structure with the SAMPLE_FREQ() macro.\r
                 */\r
                typedef struct\r


@@ -319,7 +345,9 @@
                        uint8_t                   HighByte; /**< Upper 8 bits of the 24-bit value */\r
                } USB_Audio_SampleFreq_t;\r
 \r
                        uint8_t                   HighByte; /**< Upper 8 bits of the 24-bit value */\r
                } USB_Audio_SampleFreq_t;\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


@@ -338,7 +366,9 @@
                        USB_Audio_SampleFreq_t    SampleFrequencies[AUDIO_TOTAL_SAMPLE_RATES]; /**< Sample frequencies supported by the device */\r
                } USB_Audio_Format_t;\r
                \r
                        USB_Audio_SampleFreq_t    SampleFrequencies[AUDIO_TOTAL_SAMPLE_RATES]; /**< Sample frequencies supported by the device */\r
                } USB_Audio_Format_t;\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


@@ -346,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
+                       uint8_t                   SyncEndpointNumber; /**< Endpoint address to send synchronization information to, if needed (zero otherwise) */\r

                } USB_Audio_StreamEndpoint_Std_t;\r
                                        \r
                } USB_Audio_StreamEndpoint_Std_t;\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