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