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  *  \note This file should not be included directly. It is automatically included as needed by the class driver
  35  *        dispatch header located in LUFA/Drivers/USB/Class/Audio.h.
  36  */
  37
  38 /** \ingroup Group_USBClassAudio
  39  *  @defgroup Group_USBClassAudioDevice Audio Class Device Mode Driver
  40  *
  41  *  \section Sec_Dependencies Module Source Dependencies
  42  *  The following files must be built with any user project that uses this module:
  43  *    - LUFA/Drivers/USB/Class/Device/Audio.c
  44  *
  45  *  \section Module Description
  46  *  Device Mode USB Class driver framework interface, for the Audio USB Class driver.
  47  *
  48  *  @{
  49  */
  50
  51 #ifndef _AUDIO_CLASS_DEVICE_H_
  52 #define _AUDIO_CLASS_DEVICE_H_
  53
  54         /* Includes: */
  55                 #include "../../USB.h"
  56                 #include "../Common/Audio.h"
  57
  58                 #include <string.h>
  59
  60         /* Enable C linkage for C++ Compilers: */
  61                 #if defined(__cplusplus)
  62                         extern "C" {
  63                 #endif
  64
  65         /* Preprocessor Checks: */
  66                 #if !defined(__INCLUDE_FROM_AUDIO_DRIVER)
  67                         #error Do not include this file directly. Include LUFA/Drivers/Class/Audio.h instead.
  68                 #endif
  69
  70         /* Public Interface - May be used in end-application: */
  71                 /* Type Defines: */
  72                         /** Class state structure. An instance of this structure should be made for each Audio interface
  73                          *  within the user application, and passed to each of the Audio class driver functions as the
  74                          *  AudioInterfaceInfo parameter. This stores each Audio interface's configuration and state information.
  75                          */
  76                         typedef struct
  77                         {
  78                                 const struct
  79                                 {
  80                                         uint8_t  StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this
  81                                                                                                                 *   structure controls
  82                                                                                                                 */
  83
  84                                         uint8_t  DataINEndpointNumber; /**< Endpoint number of the incoming Audio Streaming data, if available
  85                                                                                                         *   (zero if unused)
  86                                                                                                         */
  87                                         uint16_t DataINEndpointSize; /**< Size in bytes of the incoming Audio Streaming data endpoint, if available
  88                                                                                                   *   (zero if unused)
  89                                                                                                   */
  90
  91                                         uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the outgoing Audio Streaming data, if available
  92                                                                                                          *   (zero if unused)
  93                                                                                                          */
  94                                         uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing Audio Streaming data endpoint, if available
  95                                                                                                    *   (zero if unused)
  96                                                                                                    */
  97                                 } Config; /**< Config data for the USB class interface within the device. All elements in this section
  98                                            *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.
  99                                            */
 100                                 struct
 101                                 {
 102                                         bool     InterfaceEnabled; /**< Set and cleared by the class driver to indicate if the host has enabled the streaming endpoints
 103                                                                                                 *   of the Audio Streaming interface.
 104                                                                                                 */
 105                                 } State; /**< State data for the USB class interface within the device. All elements in this section
 106                                           *   are reset to their defaults when the interface is enumerated.
 107                                           */
 108                         } USB_ClassInfo_Audio_Device_t;
 109
 110                 /* Function Prototypes: */
 111                         /** Configures the endpoints of a given Audio interface, ready for use. This should be linked to the library
 112                          *  \ref EVENT_USB_Device_ConfigurationChanged() event so that the endpoints are configured when the configuration containing the
 113                          *  given Audio interface is selected.
 114                          *
 115                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 116                          *
 117                          *  \return Boolean true if the endpoints were successfully configured, false otherwise
 118                          */
 119                         bool Audio_Device_ConfigureEndpoints(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 120
 121                         /** Processes incoming control requests from the host, that are directed to the given Audio class interface. This should be
 122                          *  linked to the library \ref EVENT_USB_Device_UnhandledControlRequest() event.
 123                          *
 124                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 125                          */
 126                         void Audio_Device_ProcessControlRequest(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 127
 128                         /** Determines if the given audio interface is ready for a sample to be read from it, and selects the streaming
 129                          *  OUT endpoint ready for reading.
 130                          *
 131                          *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 132                          *        the call will fail.
 133                          *
 134                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 135                          *
 136                          *  \return Boolean true if the given Audio interface has a sample to be read, false otherwise
 137                          */
 138                         bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 139
 140                         /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects
 141                          *  the streaming IN endpoint ready for writing.
 142                          *
 143                          *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 144                          *        the call will fail.
 145                          *
 146                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 147                          *
 148                          *  \return Boolean true if the given Audio interface is ready to accept the next sample, false otherwise
 149                          */
 150                         bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 151
 152                 /* Inline Functions: */
 153                         /** General management task for a given Audio class interface, required for the correct operation of the interface. This should
 154                          *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
 155                          *
 156                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 157                          */
 158                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo);
 159                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 160                         {
 161                                 (void)AudioInterfaceInfo;
 162                         }
 163
 164                         /** Reads the next 8-bit audio sample from the current audio interface.
 165                          *
 166                          *  \note This should be preceded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
 167                          *        the correct endpoint is selected and ready for data.
 168                          *
 169                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 170                          *
 171                          *  \return  Signed 8-bit audio sample from the audio interface
 172                          */
 173                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 174                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 175                         {
 176                                 int8_t Sample;
 177
 178                                 (void)AudioInterfaceInfo;
 179
 180                                 Sample = Endpoint_Read_Byte();
 181
 182                                 if (!(Endpoint_BytesInEndpoint()))
 183                                   Endpoint_ClearOUT();
 184
 185                                 return Sample;
 186                         }
 187
 188                         /** Reads the next 16-bit audio sample from the current audio interface.
 189                          *
 190                          *  \note This should be preceded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
 191                          *        the correct endpoint is selected and ready for data.
 192                          *
 193                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 194                          *
 195                          *  \return  Signed 16-bit audio sample from the audio interface
 196                          */
 197                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 198                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 199                         {
 200                                 int16_t Sample;
 201
 202                                 (void)AudioInterfaceInfo;
 203
 204                                 Sample = (int16_t)Endpoint_Read_Word_LE();
 205
 206                                 if (!(Endpoint_BytesInEndpoint()))
 207                                   Endpoint_ClearOUT();
 208
 209                                 return Sample;
 210                         }
 211
 212                         /** Reads the next 24-bit audio sample from the current audio interface.
 213                          *
 214                          *  \note This should be preceded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
 215                          *        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                          *  \return  Signed 24-bit audio sample from the audio interface
 219                          */
 220                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_ALWAYS_INLINE;
 221                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 222                         {
 223                                 int32_t Sample;
 224
 225                                 (void)AudioInterfaceInfo;
 226
 227                                 Sample = (((uint32_t)Endpoint_Read_Byte() << 16) | Endpoint_Read_Word_LE());
 228
 229                                 if (!(Endpoint_BytesInEndpoint()))
 230                                   Endpoint_ClearOUT();
 231
 232                                 return Sample;
 233                         }
 234
 235                         /** Writes the next 8-bit audio sample to the current audio interface.
 236                          *
 237                          *  \note This should be preceded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
 238                          *        the correct endpoint is selected and ready for data.
 239                          *
 240                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state
 241                          *  \param[in] Sample  Signed 8-bit audio sample
 242                          */
 243                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 244                                                                      const int8_t Sample) ATTR_ALWAYS_INLINE;
 245                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 246                                                                      const int8_t Sample)
 247                         {
 248                                 Endpoint_Write_Byte(Sample);
 249
 250                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 251                                   Endpoint_ClearIN();
 252                         }
 253
 254                         /** Writes the next 16-bit audio sample to the current audio interface.
 255                          *
 256                          *  \note This should be preceded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
 257                          *        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 16-bit audio sample
 261                          */
 262                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 263                                                                       const int16_t Sample) ATTR_ALWAYS_INLINE;
 264                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 265                                                                       const int16_t Sample)
 266                         {
 267                                 Endpoint_Write_Word_LE(Sample);
 268
 269                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 270                                   Endpoint_ClearIN();
 271                         }
 272
 273                         /** Writes the next 24-bit audio sample to the current audio interface.
 274                          *
 275                          *  \note This should be preceded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
 276                          *        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 24-bit audio sample
 280                          */
 281                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 282                                                                       const int32_t Sample) ATTR_ALWAYS_INLINE;
 283                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 284                                                                       const int32_t Sample)
 285                         {
 286                                 Endpoint_Write_Byte(Sample >> 16);
 287                                 Endpoint_Write_Word_LE(Sample);
 288
 289                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 290                                   Endpoint_ClearIN();
 291                         }
 292
 293         /* Disable C linkage for C++ Compilers: */
 294                 #if defined(__cplusplus)
 295                         }
 296                 #endif
 297
 298 #endif
 299
 300 /** @} */