LUFA/Drivers/USB/Class/Device/Audio.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2010.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief Device mode driver for the library USB Audio Class driver.
  33  *
  34  *  Device mode driver for the library USB Audio Class driver.
  35  *
  36  *  \note This file should not be included directly. It is automatically included as needed by the class driver
  37  *        dispatch header located in LUFA/Drivers/USB/Class/Audio.h.
  38  */
  39
  40 /** \ingroup Group_USBClassAudio
  41  *  @defgroup Group_USBClassAudioDevice Audio Class Device Mode Driver
  42  *
  43  *  \section Sec_Dependencies Module Source Dependencies
  44  *  The following files must be built with any user project that uses this module:
  45  *    - LUFA/Drivers/USB/Class/Device/Audio.c
  46  *
  47  *  \section Module Description
  48  *  Device Mode USB Class driver framework interface, for the Audio USB Class driver.
  49  *
  50  *  @{
  51  */
  52
  53 #ifndef _AUDIO_CLASS_DEVICE_H_
  54 #define _AUDIO_CLASS_DEVICE_H_
  55
  56         /* Includes: */
  57                 #include "../../USB.h"
  58                 #include "../Common/Audio.h"
  59
  60                 #include <string.h>
  61
  62         /* Enable C linkage for C++ Compilers: */
  63                 #if defined(__cplusplus)
  64                         extern "C" {
  65                 #endif
  66
  67         /* Preprocessor Checks: */
  68                 #if !defined(__INCLUDE_FROM_AUDIO_DRIVER)
  69                         #error Do not include this file directly. Include LUFA/Drivers/Class/Audio.h instead.
  70                 #endif
  71
  72         /* Public Interface - May be used in end-application: */
  73                 /* Type Defines: */
  74                         /** \brief Audio Class Device Mode Configuration and State Structure.
  75                          *
  76                          *  Class state structure. An instance of this structure should be made for each Audio interface
  77                          *  within the user application, and passed to each of the Audio class driver functions as the
  78                          *  AudioInterfaceInfo parameter. This stores each Audio interface's configuration and state information.
  79                          */
  80                         typedef struct
  81                         {
  82                                 const struct
  83                                 {
  84                                         uint8_t  StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this
  85                                                                                                                 *   structure controls
  86                                                                                                                 */
  87
  88                                         uint8_t  DataINEndpointNumber; /**< Endpoint number of the incoming Audio Streaming data, if available
  89                                                                                                         *   (zero if unused)
  90                                                                                                         */
  91                                         uint16_t DataINEndpointSize; /**< Size in bytes of the incoming Audio Streaming data endpoint, if available
  92                                                                                                   *   (zero if unused)
  93                                                                                                   */
  94
  95                                         uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the outgoing Audio Streaming data, if available
  96                                                                                                          *   (zero if unused)
  97                                                                                                          */
  98                                         uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing Audio Streaming data endpoint, if available
  99                                                                                                    *   (zero if unused)
 100                                                                                                    */
 101                                 } Config; /**< Config data for the USB class interface within the device. All elements in this section
 102                                            *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.
 103                                            */
 104                                 struct
 105                                 {
 106                                         bool     InterfaceEnabled; /**< Set and cleared by the class driver to indicate if the host has enabled the streaming endpoints
 107                                                                                                 *   of the Audio Streaming interface.
 108                                                                                                 */
 109                                 } State; /**< State data for the USB class interface within the device. All elements in this section
 110                                           *   are reset to their defaults when the interface is enumerated.
 111                                           */
 112                         } USB_ClassInfo_Audio_Device_t;
 113
 114                 /* Function Prototypes: */
 115                         /** Configures the endpoints of a given Audio interface, ready for use. This should be linked to the library
 116                          *  \ref EVENT_USB_Device_ConfigurationChanged() event so that the endpoints are configured when the configuration containing the
 117                          *  given Audio interface is selected.
 118                          *
 119                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 120                          *
 121                          *  \return Boolean true if the endpoints were successfully configured, false otherwise
 122                          */
 123                         bool Audio_Device_ConfigureEndpoints(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 124
 125                         /** Processes incoming control requests from the host, that are directed to the given Audio class interface. This should be
 126                          *  linked to the library \ref EVENT_USB_Device_UnhandledControlRequest() event.
 127                          *
 128                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 129                          */
 130                         void Audio_Device_ProcessControlRequest(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 131
 132                 /* Inline Functions: */
 133                         /** General management task for a given Audio class interface, required for the correct operation of the interface. This should
 134                          *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
 135                          *
 136                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 137                          */
 138                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 139                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 140                         {
 141                                 (void)AudioInterfaceInfo;
 142                         }
 143
 144                         /** Determines if the given audio interface is ready for a sample to be read from it, and selects the streaming
 145                          *  OUT endpoint ready for reading.
 146                          *
 147                          *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 148                          *        the call will fail.
 149                          *
 150                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 151                          *
 152                          *  \return Boolean true if the given Audio interface has a sample to be read, false otherwise
 153                          */
 154                         static inline bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 155                         {
 156                                 if ((USB_DeviceState != DEVICE_STATE_Configured) || !(AudioInterfaceInfo->State.InterfaceEnabled))
 157                                   return false;
 158
 159                                 Endpoint_SelectEndpoint(AudioInterfaceInfo->Config.DataOUTEndpointNumber);
 160                                 return Endpoint_IsOUTReceived();
 161                         }
 162
 163                         /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects
 164                          *  the streaming IN endpoint ready for writing.
 165                          *
 166                          *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 167                          *        the call will fail.
 168                          *
 169                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 170                          *
 171                          *  \return Boolean true if the given Audio interface is ready to accept the next sample, false otherwise
 172                          */
 173                         static inline bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 174                         {
 175                                 if ((USB_DeviceState != DEVICE_STATE_Configured) || !(AudioInterfaceInfo->State.InterfaceEnabled))
 176                                   return false;
 177
 178                                 Endpoint_SelectEndpoint(AudioInterfaceInfo->Config.DataINEndpointNumber);
 179                                 return Endpoint_IsINReady();
 180                         }
 181
 182                         /** Reads the next 8-bit audio sample from the current audio interface.
 183                          *
 184                          *  \note This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 185                          *        ensure the correct endpoint is selected and ready for data.
 186                          *
 187                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 188                          *
 189                          *  \return  Signed 8-bit audio sample from the audio interface
 190                          */
 191                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 192                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 193                         {
 194                                 int8_t Sample;
 195
 196                                 (void)AudioInterfaceInfo;
 197
 198                                 Sample = Endpoint_Read_Byte();
 199
 200                                 if (!(Endpoint_BytesInEndpoint()))
 201                                   Endpoint_ClearOUT();
 202
 203                                 return Sample;
 204                         }
 205
 206                         /** Reads the next 16-bit audio sample from the current audio interface.
 207                          *
 208                          *  \note This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 209                          *        that the correct endpoint is selected and ready for data.
 210                          *
 211                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 212                          *
 213                          *  \return  Signed 16-bit audio sample from the audio interface
 214                          */
 215                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 216                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 217                         {
 218                                 int16_t Sample;
 219
 220                                 (void)AudioInterfaceInfo;
 221
 222                                 Sample = (int16_t)Endpoint_Read_Word_LE();
 223
 224                                 if (!(Endpoint_BytesInEndpoint()))
 225                                   Endpoint_ClearOUT();
 226
 227                                 return Sample;
 228                         }
 229
 230                         /** Reads the next 24-bit audio sample from the current audio interface.
 231                          *
 232                          *  \note This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 233                          *        that the correct endpoint is selected and ready for data.
 234                          *
 235                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 236                          *
 237                          *  \return  Signed 24-bit audio sample from the audio interface
 238                          */
 239                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 240                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 241                         {
 242                                 int32_t Sample;
 243
 244                                 (void)AudioInterfaceInfo;
 245
 246                                 Sample = (((uint32_t)Endpoint_Read_Byte() << 16) | Endpoint_Read_Word_LE());
 247
 248                                 if (!(Endpoint_BytesInEndpoint()))
 249                                   Endpoint_ClearOUT();
 250
 251                                 return Sample;
 252                         }
 253
 254                         /** Writes the next 8-bit audio sample to the current audio interface.
 255                          *
 256                          *  \note This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 257                          *        ensure that the correct endpoint is selected and ready for data.
 258                          *
 259                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 260                          *  \param[in] Sample  Signed 8-bit audio sample
 261                          */
 262                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 263                                                                      const int8_t Sample) ATTR_ALWAYS_INLINE;
 264                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 265                                                                      const int8_t Sample)
 266                         {
 267                                 Endpoint_Write_Byte(Sample);
 268
 269                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 270                                   Endpoint_ClearIN();
 271                         }
 272
 273                         /** Writes the next 16-bit audio sample to the current audio interface.
 274                          *
 275                          *  \note This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 276                          *        ensure that the correct endpoint is selected and ready for data.
 277                          *
 278                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 279                          *  \param[in] Sample  Signed 16-bit audio sample
 280                          */
 281                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 282                                                                       const int16_t Sample) ATTR_ALWAYS_INLINE;
 283                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 284                                                                       const int16_t Sample)
 285                         {
 286                                 Endpoint_Write_Word_LE(Sample);
 287
 288                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 289                                   Endpoint_ClearIN();
 290                         }
 291
 292                         /** Writes the next 24-bit audio sample to the current audio interface.
 293                          *
 294                          *  \note This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 295                          *        ensure that the correct endpoint is selected and ready for data.
 296                          *
 297                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 298                          *  \param[in] Sample  Signed 24-bit audio sample
 299                          */
 300                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 301                                                                       const int32_t Sample) ATTR_ALWAYS_INLINE;
 302                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 303                                                                       const int32_t Sample)
 304                         {
 305                                 Endpoint_Write_Byte(Sample >> 16);
 306                                 Endpoint_Write_Word_LE(Sample);
 307
 308                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 309                                   Endpoint_ClearIN();
 310                         }
 311
 312         /* Disable C linkage for C++ Compilers: */
 313                 #if defined(__cplusplus)
 314                         }
 315                 #endif
 316
 317 #endif
 318
 319 /** @} */