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

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  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 USB module driver
  37  *        dispatch header located in LUFA/Drivers/USB.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 Sec_ModDescription 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/USB.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                          *  \c 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                          *  \note The endpoint index numbers as given in the interface's configuration structure must not overlap with any other
 120                          *        interface, or endpoint bank corruption will occur. Gaps in the allocated endpoint numbers or non-sequential indexes
 121                          *        within a single interface is allowed, but no two interfaces of any type have have interleaved endpoint indexes.
 122                          *
 123                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 124                          *
 125                          *  \return Boolean \c true if the endpoints were successfully configured, \c false otherwise.
 126                          */
 127                         bool Audio_Device_ConfigureEndpoints(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 128
 129                         /** Processes incoming control requests from the host, that are directed to the given Audio class interface. This should be
 130                          *  linked to the library \ref EVENT_USB_Device_ControlRequest() event.
 131                          *
 132                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 133                          */
 134                         void Audio_Device_ProcessControlRequest(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 135
 136                 /* Inline Functions: */
 137                         /** General management task for a given Audio class interface, required for the correct operation of the interface. This should
 138                          *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
 139                          *
 140                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 141                          */
 142                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 143                                                                 ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 144                         static inline void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 145                         {
 146                                 (void)AudioInterfaceInfo;
 147                         }
 148
 149                         /** Determines if the given audio interface is ready for a sample to be read from it, and selects the streaming
 150                          *  OUT endpoint ready for reading.
 151                          *
 152                          *  \pre This function must only be called when the Device state machine is in the \ref DEVICE_STATE_Configured state or
 153                          *       the call will fail.
 154                          *
 155                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 156                          *
 157                          *  \return Boolean \c true if the given Audio interface has a sample to be read, \c false otherwise.
 158                          */
 159                         static inline bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 160                                                                          ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 161                         static inline bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 162                         {
 163                                 if ((USB_DeviceState != DEVICE_STATE_Configured) || !(AudioInterfaceInfo->State.InterfaceEnabled))
 164                                   return false;
 165
 166                                 Endpoint_SelectEndpoint(AudioInterfaceInfo->Config.DataOUTEndpointNumber);
 167                                 return Endpoint_IsOUTReceived();
 168                         }
 169
 170                         /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects
 171                          *  the streaming IN endpoint ready for writing.
 172                          *
 173                          *  \pre This function must only be called when the Device state machine is in the \ref DEVICE_STATE_Configured state or
 174                          *       the call will fail.
 175                          *
 176                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 177                          *
 178                          *  \return Boolean \c true if the given Audio interface is ready to accept the next sample, \c false otherwise.
 179                          */
 180                         static inline bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 181                                                                              ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 182                         static inline bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 183                         {
 184                                 if ((USB_DeviceState != DEVICE_STATE_Configured) || !(AudioInterfaceInfo->State.InterfaceEnabled))
 185                                   return false;
 186
 187                                 Endpoint_SelectEndpoint(AudioInterfaceInfo->Config.DataINEndpointNumber);
 188                                 return Endpoint_IsINReady();
 189                         }
 190
 191                         /** Reads the next 8-bit audio sample from the current audio interface.
 192                          *
 193                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 194                          *       ensure the correct endpoint is selected and ready for data.
 195                          *
 196                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 197                          *
 198                          *  \return  Signed 8-bit audio sample from the audio interface.
 199                          */
 200                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 201                                                                       ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 202                         static inline int8_t Audio_Device_ReadSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 203                         {
 204                                 int8_t Sample;
 205
 206                                 (void)AudioInterfaceInfo;
 207
 208                                 Sample = Endpoint_Read_Byte();
 209
 210                                 if (!(Endpoint_BytesInEndpoint()))
 211                                   Endpoint_ClearOUT();
 212
 213                                 return Sample;
 214                         }
 215
 216                         /** Reads the next 16-bit audio sample from the current audio interface.
 217                          *
 218                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 219                          *       that 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                          *
 223                          *  \return  Signed 16-bit audio sample from the audio interface.
 224                          */
 225                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 226                                                                         ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 227                         static inline int16_t Audio_Device_ReadSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 228                         {
 229                                 int16_t Sample;
 230
 231                                 (void)AudioInterfaceInfo;
 232
 233                                 Sample = (int16_t)Endpoint_Read_Word_LE();
 234
 235                                 if (!(Endpoint_BytesInEndpoint()))
 236                                   Endpoint_ClearOUT();
 237
 238                                 return Sample;
 239                         }
 240
 241                         /** Reads the next 24-bit audio sample from the current audio interface.
 242                          *
 243                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsSampleReceived() function to ensure
 244                          *       that the correct endpoint is selected and ready for data.
 245                          *
 246                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 247                          *
 248                          *  \return Signed 24-bit audio sample from the audio interface.
 249                          */
 250                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 251                                                                         ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 252                         static inline int32_t Audio_Device_ReadSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo)
 253                         {
 254                                 int32_t Sample;
 255
 256                                 (void)AudioInterfaceInfo;
 257
 258                                 Sample = (((uint32_t)Endpoint_Read_Byte() << 16) | Endpoint_Read_Word_LE());
 259
 260                                 if (!(Endpoint_BytesInEndpoint()))
 261                                   Endpoint_ClearOUT();
 262
 263                                 return Sample;
 264                         }
 265
 266                         /** Writes the next 8-bit audio sample to the current audio interface.
 267                          *
 268                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 269                          *       ensure that the correct endpoint is selected and ready for data.
 270                          *
 271                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 272                          *  \param[in]     Sample              Signed 8-bit audio sample.
 273                          */
 274                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 275                                                                      const int8_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 276                         static inline void Audio_Device_WriteSample8(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 277                                                                      const int8_t Sample)
 278                         {
 279                                 Endpoint_Write_Byte(Sample);
 280
 281                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 282                                   Endpoint_ClearIN();
 283                         }
 284
 285                         /** Writes the next 16-bit audio sample to the current audio interface.
 286                          *
 287                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 288                          *       ensure that the correct endpoint is selected and ready for data.
 289                          *
 290                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 291                          *  \param[in]     Sample              Signed 16-bit audio sample.
 292                          */
 293                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 294                                                                       const int16_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 295                         static inline void Audio_Device_WriteSample16(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 296                                                                       const int16_t Sample)
 297                         {
 298                                 Endpoint_Write_Word_LE(Sample);
 299
 300                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 301                                   Endpoint_ClearIN();
 302                         }
 303
 304                         /** Writes the next 24-bit audio sample to the current audio interface.
 305                          *
 306                          *  \pre This should be preceded immediately by a call to the \ref Audio_Device_IsReadyForNextSample() function to
 307                          *       ensure that the correct endpoint is selected and ready for data.
 308                          *
 309                          *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
 310                          *  \param[in]     Sample              Signed 24-bit audio sample.
 311                          */
 312                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 313                                                                       const int32_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 314                         static inline void Audio_Device_WriteSample24(USB_ClassInfo_Audio_Device_t* const AudioInterfaceInfo,
 315                                                                       const int32_t Sample)
 316                         {
 317                                 Endpoint_Write_Word_LE(Sample);
 318                                 Endpoint_Write_Byte(Sample >> 16);
 319
 320                                 if (Endpoint_BytesInEndpoint() == AudioInterfaceInfo->Config.DataINEndpointSize)
 321                                   Endpoint_ClearIN();
 322                         }
 323
 324         /* Disable C linkage for C++ Compilers: */
 325                 #if defined(__cplusplus)
 326                         }
 327                 #endif
 328
 329 #endif
 330
 331 /** @} */
 332