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 1.0 Class driver.
  33  *
  34  *  Device mode driver for the library USB Audio 1.0 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 <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
  46  *
  47  *  \section Module Description
  48  *  Device Mode USB Class driver framework interface, for the Audio 1.0 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                                                                 ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 140                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 141                         {
 142                                 (void)AudioInterfaceInfo;
 143                         }
 144
 145                         /** Determines if the given audio interface is ready for a sample to be read from it, and selects the streaming
 146                          *  OUT endpoint ready for reading.
 147                          *
 148                          *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 149                          *       the call will fail.
 150                          *
 151                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 152                          *
 153                          *  \return Boolean true if the given Audio interface has a sample to be read, false otherwise.
 154                          */
 155                         static inline bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 156                                                                          ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 157                         static inline bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 158                         {
 159                                 if ((USB_DeviceState != DEVICE_STATE_Configured) || !(AudioInterfaceInfo->State.InterfaceEnabled))
 160                                   return false;
 161
 162                                 Endpoint_SelectEndpoint(AudioInterfaceInfo->Config.DataOUTEndpointNumber);
 163                                 return Endpoint_IsOUTReceived();
 164                         }
 165
 166                         /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects
 167                          *  the streaming IN endpoint ready for writing.
 168                          *
 169                          *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 170                          *       the call will fail.
 171                          *
 172                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 173                          *
 174                          *  \return Boolean true if the given Audio interface is ready to accept the next sample, false otherwise.
 175                          */
 176                         static inline bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 177                                                                              ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 178                         static inline bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 179                         {
 180                                 if ((USB_DeviceState != DEVICE_STATE_Configured) || !(AudioInterfaceInfo->State.InterfaceEnabled))
 181                                   return false;
 182
 183                                 Endpoint_SelectEndpoint(AudioInterfaceInfo->Config.DataINEndpointNumber);
 184                                 return Endpoint_IsINReady();
 185                         }
 186
 187                         /** Reads the next 8-bit audio sample from the current audio interface.
 188                          *
 189                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 190                          *       ensure the correct endpoint is selected and ready for data.
 191                          *
 192                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 193                          *
 194                          *  \return  Signed 8-bit audio sample from the audio interface.
 195                          */
 196                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 197                                                                       ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 198                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 199                         {
 200                                 int8_t Sample;
 201
 202                                 (void)AudioInterfaceInfo;
 203
 204                                 Sample = Endpoint_Read_Byte();
 205
 206                                 if (!(Endpoint_BytesInEndpoint()))
 207                                   Endpoint_ClearOUT();
 208
 209                                 return Sample;
 210                         }
 211
 212                         /** Reads the next 16-bit audio sample from the current audio interface.
 213                          *
 214                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 215                          *       that the correct endpoint is selected and ready for data.
 216                          *
 217                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 218                          *
 219                          *  \return  Signed 16-bit audio sample from the audio interface.
 220                          */
 221                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 222                                                                         ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 223                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 224                         {
 225                                 int16_t Sample;
 226
 227                                 (void)AudioInterfaceInfo;
 228
 229                                 Sample = (int16_t)Endpoint_Read_Word_LE();
 230
 231                                 if (!(Endpoint_BytesInEndpoint()))
 232                                   Endpoint_ClearOUT();
 233
 234                                 return Sample;
 235                         }
 236
 237                         /** Reads the next 24-bit audio sample from the current audio interface.
 238                          *
 239                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 240                          *       that the correct endpoint is selected and ready for data.
 241                          *
 242                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 243                          *
 244                          *  \return Signed 24-bit audio sample from the audio interface.
 245                          */
 246                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 247                                                                         ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 248                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 249                         {
 250                                 int32_t Sample;
 251
 252                                 (void)AudioInterfaceInfo;
 253
 254                                 Sample = (((uint32_t)Endpoint_Read_Byte() << 16) | Endpoint_Read_Word_LE());
 255
 256                                 if (!(Endpoint_BytesInEndpoint()))
 257                                   Endpoint_ClearOUT();
 258
 259                                 return Sample;
 260                         }
 261
 262                         /** Writes the next 8-bit audio sample to the current audio interface.
 263                          *
 264                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 265                          *       ensure that the correct endpoint is selected and ready for data.
 266                          *
 267                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 268                          *  \param[in]     Sample              Signed 8-bit audio sample.
 269                          */
 270                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 271                                                                      const int8_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 272                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 273                                                                      const int8_t Sample)
 274                         {
 275                                 Endpoint_Write_Byte(Sample);
 276
 277                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 278                                   Endpoint_ClearIN();
 279                         }
 280
 281                         /** Writes the next 16-bit audio sample to the current audio interface.
 282                          *
 283                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 284                          *       ensure that the correct endpoint is selected and ready for data.
 285                          *
 286                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 287                          *  \param[in]     Sample              Signed 16-bit audio sample.
 288                          */
 289                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 290                                                                       const int16_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 291                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 292                                                                       const int16_t Sample)
 293                         {
 294                                 Endpoint_Write_Word_LE(Sample);
 295
 296                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 297                                   Endpoint_ClearIN();
 298                         }
 299
 300                         /** Writes the next 24-bit audio sample to the current audio interface.
 301                          *
 302                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 303                          *       ensure that the correct endpoint is selected and ready for data.
 304                          *
 305                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 306                          *  \param[in]     Sample              Signed 24-bit audio sample.
 307                          */
 308                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 309                                                                       const int32_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 310                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 311                                                                       const int32_t Sample)
 312                         {
 313                                 Endpoint_Write_Byte(Sample >> 16);
 314                                 Endpoint_Write_Word_LE(Sample);
 315
 316                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 317                                   Endpoint_ClearIN();
 318                         }
 319
 320         /* Disable C linkage for C++ Compilers: */
 321                 #if defined(__cplusplus)
 322                         }
 323                 #endif
 324
 325 #endif
 326
 327 /** @} */