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                         /** Determines if the given audio interface is ready for a sample to be read from it, and selects the streaming
 133                          *  OUT endpoint ready for reading.
 134                          *
 135                          *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 136                          *        the call will fail.
 137                          *
 138                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 139                          *
 140                          *  \return Boolean true if the given Audio interface has a sample to be read, false otherwise
 141                          */
 142                         bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 143
 144                         /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects
 145                          *  the streaming IN endpoint ready for writing.
 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 is ready to accept the next sample, false otherwise
 153                          */
 154                         bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 155
 156                 /* Inline Functions: */
 157                         /** General management task for a given Audio class interface, required for the correct operation of the interface. This should
 158                          *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
 159                          *
 160                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 161                          */
 162                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 163                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 164                         {
 165                                 (void)AudioInterfaceInfo;
 166                         }
 167
 168                         /** Reads the next 8-bit audio sample from the current audio interface.
 169                          *
 170                          *  \note This should be preceded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
 171                          *        the correct endpoint is selected and ready for data.
 172                          *
 173                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 174                          *
 175                          *  \return  Signed 8-bit audio sample from the audio interface
 176                          */
 177                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 178                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 179                         {
 180                                 int8_t Sample;
 181
 182                                 (void)AudioInterfaceInfo;
 183
 184                                 Sample = Endpoint_Read_Byte();
 185
 186                                 if (!(Endpoint_BytesInEndpoint()))
 187                                   Endpoint_ClearOUT();
 188
 189                                 return Sample;
 190                         }
 191
 192                         /** Reads the next 16-bit audio sample from the current audio interface.
 193                          *
 194                          *  \note This should be preceded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
 195                          *        the correct endpoint is selected and ready for data.
 196                          *
 197                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 198                          *
 199                          *  \return  Signed 16-bit audio sample from the audio interface
 200                          */
 201                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 202                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 203                         {
 204                                 int16_t Sample;
 205
 206                                 (void)AudioInterfaceInfo;
 207
 208                                 Sample = (int16_t)Endpoint_Read_Word_LE();
 209
 210                                 if (!(Endpoint_BytesInEndpoint()))
 211                                   Endpoint_ClearOUT();
 212
 213                                 return Sample;
 214                         }
 215
 216                         /** Reads the next 24-bit audio sample from the current audio interface.
 217                          *
 218                          *  \note This should be preceded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
 219                          *        the correct endpoint is selected and ready for data.
 220                          *
 221                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 222                          *  \return  Signed 24-bit audio sample from the audio interface
 223                          */
 224                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 225                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 226                         {
 227                                 int32_t Sample;
 228
 229                                 (void)AudioInterfaceInfo;
 230
 231                                 Sample = (((uint32_t)Endpoint_Read_Byte() << 16) | Endpoint_Read_Word_LE());
 232
 233                                 if (!(Endpoint_BytesInEndpoint()))
 234                                   Endpoint_ClearOUT();
 235
 236                                 return Sample;
 237                         }
 238
 239                         /** Writes the next 8-bit audio sample to the current audio interface.
 240                          *
 241                          *  \note This should be preceded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
 242                          *        the correct endpoint is selected and ready for data.
 243                          *
 244                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 245                          *  \param[in] Sample  Signed 8-bit audio sample
 246                          */
 247                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 248                                                                      const int8_t Sample) ATTR_ALWAYS_INLINE;
 249                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 250                                                                      const int8_t Sample)
 251                         {
 252                                 Endpoint_Write_Byte(Sample);
 253
 254                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 255                                   Endpoint_ClearIN();
 256                         }
 257
 258                         /** Writes the next 16-bit audio sample to the current audio interface.
 259                          *
 260                          *  \note This should be preceded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
 261                          *        the correct endpoint is selected and ready for data.
 262                          *
 263                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 264                          *  \param[in] Sample  Signed 16-bit audio sample
 265                          */
 266                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 267                                                                       const int16_t Sample) ATTR_ALWAYS_INLINE;
 268                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 269                                                                       const int16_t Sample)
 270                         {
 271                                 Endpoint_Write_Word_LE(Sample);
 272
 273                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 274                                   Endpoint_ClearIN();
 275                         }
 276
 277                         /** Writes the next 24-bit audio sample to the current audio interface.
 278                          *
 279                          *  \note This should be preceded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
 280                          *        the correct endpoint is selected and ready for data.
 281                          *
 282                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 283                          *  \param[in] Sample  Signed 24-bit audio sample
 284                          */
 285                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 286                                                                       const int32_t Sample) ATTR_ALWAYS_INLINE;
 287                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 288                                                                       const int32_t Sample)
 289                         {
 290                                 Endpoint_Write_Byte(Sample >> 16);
 291                                 Endpoint_Write_Word_LE(Sample);
 292
 293                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 294                                   Endpoint_ClearIN();
 295                         }
 296
 297         /* Disable C linkage for C++ Compilers: */
 298                 #if defined(__cplusplus)
 299                         }
 300                 #endif
 301
 302 #endif
 303
 304 /** @} */