Audio.h 18.8 KB
 Dean Camera committed Jun 08, 2011 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 /* LUFA Library Copyright (C) Dean Camera, 2011. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that the copyright notice and this 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 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 Jun 08, 2011 32  * \brief Host mode driver for the library USB Audio 1.0 Class driver.  Dean Camera committed Jun 08, 2011 33  *  Dean Camera committed Jun 08, 2011 34  * Host mode driver for the library USB Audio 1.0 Class driver.  Dean Camera committed Jun 08, 2011 35 36 37 38 39 40  * * \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. */ /** \ingroup Group_USBClassAudio  Dean Camera committed Jun 08, 2011 41  * \defgroup Group_USBClassAudioHost Audio 1.0 Class Host Mode Driver  Dean Camera committed Jun 08, 2011 42 43 44 45 46 47  * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module: * - LUFA/Drivers/USB/Class/Host/Audio.c (Makefile source module name: LUFA_SRC_USBCLASS) * * \section Sec_ModDescription Module Description  Dean Camera committed Jun 08, 2011 48  * Host Mode USB Class driver framework interface, for the Audio 1.0 USB Class driver.  Dean Camera committed Jun 08, 2011 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81  * * @{ */ #ifndef __AUDIO_CLASS_HOST_H__ #define __AUDIO_CLASS_HOST_H__ /* Includes: */ #include "../../USB.h" #include "../Common/Audio.h" /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor Checks: */ #if !defined(__INCLUDE_FROM_AUDIO_DRIVER) #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. #endif /* Public Interface - May be used in end-application: */ /* Type Defines: */ /** \brief Audio Class Host Mode Configuration and State Structure. * * Class state structure. An instance of this structure should be made within the user application, * and passed to each of the Audio class driver functions as the \c AudioInterfaceInfo parameter. This * stores each Audio interface's configuration and state information. */ typedef struct { const struct {  Dean Camera committed Jun 12, 2011 82 83 84 85 86 87 88 89  uint8_t DataINPipeNumber; /**< Pipe number of the Audio interface's IN data pipe. If this interface should not * bind to an IN endpoint, this may be set to 0 to disable audio input streaming for * this driver instance. */ uint8_t DataOUTPipeNumber; /**< Pipe number of the Audio interface's OUT data pipe. If this interface should not * bind to an OUT endpoint, this may be set to 0 to disable audio output streaming for * this driver instance. */  Dean Camera committed Jun 08, 2011 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146  } 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 IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid * after \ref Audio_Host_ConfigurePipes() is called and the Host state machine is in the * Configured state. */ uint8_t ControlInterfaceNumber; /**< Interface index of the Audio Control interface within the attached device. */ uint8_t StreamingInterfaceNumber; /**< Interface index of the Audio Streaming interface within the attached device. */ uint8_t EnabledStreamingAltIndex; /**< Alternative setting index of the Audio Streaming interface when the stream is enabled. */ uint16_t DataINPipeSize; /**< Size in bytes of the Audio interface's IN data pipe. */ uint16_t DataOUTPipeSize; /**< Size in bytes of the Audio interface's OUT data pipe. */ } State; /**< State data for the USB class interface within the device. All elements in this section * may be set to initial values, but may also be ignored to default to sane values when * the interface is enumerated. */ } USB_ClassInfo_Audio_Host_t; /* Enums: */ /** Enum for the possible error codes returned by the \ref Audio_Host_ConfigurePipes() function. */ enum AUDIO_Host_EnumerationFailure_ErrorCodes_t { AUDIO_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */ AUDIO_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */ AUDIO_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible AUDIO interface was not found in the device's Configuration Descriptor. */ AUDIO_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */ }; /* Function Prototypes: */ /** Host interface configuration routine, to configure a given Audio host interface instance using the Configuration * Descriptor read from an attached USB device. This function automatically updates the given Audio Host instance's * state values and configures the pipes required to communicate with the interface if it is found within the * device. This should be called once after the stack has enumerated the attached device, while the host state * machine is in the Addressed state. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class host configuration and state. * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor. * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor. * * \return A value from the \ref AUDIO_Host_EnumerationFailure_ErrorCodes_t enum. */ uint8_t Audio_Host_ConfigurePipes(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, uint16_t ConfigDescriptorSize, void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3); /** Starts or stops the audio streaming for the given configured Audio Host interface, allowing for audio samples to be * send and/or received. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class host configuration and state. * \param[in] EnableStreaming Boolean true to enable streaming of the specified interface, false to disable * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum. */  Dean Camera committed Jun 08, 2011 147  uint8_t Audio_Host_StartStopStreaming(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,  Dean Camera committed Jun 13, 2011 148  const bool EnableStreaming);  Dean Camera committed Jun 08, 2011 149   Dean Camera committed Jun 08, 2011 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167  /** Gets or sets the specified property of a streaming audio class endpoint that is bound to a pipe in the given * class instance. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class host configuration and state. * \param[in] DataPipeIndex Index of the data pipe whose bound endpoint is to be altered. * \param[in] EndpointProperty Property of the endpoint to get or set, a value from \ref Audio_ClassRequests_t. * \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. * \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 A value from the \ref USB_Host_SendControlErrorCodes_t enum. */ uint8_t Audio_GetSetEndpointProperty(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const uint8_t DataPipeIndex, const uint8_t EndpointProperty, const uint8_t EndpointControl,  Dean Camera committed Jun 13, 2011 168  const uint16_t DataLength,  Dean Camera committed Jun 09, 2011 169  void* const Data);  Dean Camera committed Jun 08, 2011 170   Dean Camera committed Jun 08, 2011 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200  /* Inline Functions: */ /** General management task for a given Audio host 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(). * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class host configuration and state. */ static inline void Audio_Host_USBTask(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo); static inline void Audio_Host_USBTask(USB_ClassInfo_Audio_Host_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 * IN pipe ready for reading. * * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or * the call will fail. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * * \return Boolean \c true if the given Audio interface has a sample to be read, \c false otherwise. */ static inline bool Audio_Host_IsSampleReceived(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline bool Audio_Host_IsSampleReceived(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) { if ((USB_HostState != HOST_STATE_Configured) || !(AudioInterfaceInfo->State.IsActive)) return false;  Dean Camera committed Jun 09, 2011 201 202  bool SampleReceived = false;  Dean Camera committed Jun 09, 2011 203  Pipe_SelectPipe(AudioInterfaceInfo->Config.DataINPipeNumber);  Dean Camera committed Jun 09, 2011 204 205 206  Pipe_Unfreeze(); SampleReceived = Pipe_IsINReceived(); Pipe_Freeze();  Dean Camera committed Jun 09, 2011 207   Dean Camera committed Jun 09, 2011 208  return SampleReceived;  Dean Camera committed Jun 08, 2011 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227  } /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects * the streaming OUT pipe ready for writing. * * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or * the call will fail. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * * \return Boolean \c true if the given Audio interface is ready to accept the next sample, \c false otherwise. */ static inline bool Audio_Host_IsReadyForNextSample(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline bool Audio_Host_IsReadyForNextSample(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) { if ((USB_HostState != HOST_STATE_Configured) || !(AudioInterfaceInfo->State.IsActive)) return false;  Dean Camera committed Jun 09, 2011 228  Pipe_SelectPipe(AudioInterfaceInfo->Config.DataOUTPipeNumber);  Dean Camera committed Jun 08, 2011 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251  return Pipe_IsOUTReady(); } /** Reads the next 8-bit audio sample from the current audio interface. * * \pre This should be preceded immediately by a call to the \ref Audio_Host_IsSampleReceived() function to ensure * that the correct pipe is selected and ready for data. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * * \return Signed 8-bit audio sample from the audio interface. */ static inline int8_t Audio_Host_ReadSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline int8_t Audio_Host_ReadSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) { int8_t Sample; (void)AudioInterfaceInfo; Sample = Pipe_Read_8(); if (!(Pipe_BytesInPipe()))  Dean Camera committed Jun 09, 2011 252 253 254 255 256  { Pipe_Unfreeze(); Pipe_ClearIN(); Pipe_Freeze(); }  Dean Camera committed Jun 08, 2011 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280  return Sample; } /** Reads the next 16-bit audio sample from the current audio interface. * * \pre This should be preceded immediately by a call to the \ref Audio_Host_IsSampleReceived() function to ensure * that the correct pipe is selected and ready for data. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * * \return Signed 16-bit audio sample from the audio interface. */ static inline int16_t Audio_Host_ReadSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline int16_t Audio_Host_ReadSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) { int16_t Sample; (void)AudioInterfaceInfo; Sample = (int16_t)Pipe_Read_16_LE(); if (!(Pipe_BytesInPipe()))  Dean Camera committed Jun 09, 2011 281 282 283 284 285  { Pipe_Unfreeze(); Pipe_ClearIN(); Pipe_Freeze(); }  Dean Camera committed Jun 08, 2011 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309  return Sample; } /** Reads the next 24-bit audio sample from the current audio interface. * * \pre This should be preceded immediately by a call to the \ref Audio_Host_IsSampleReceived() function to ensure * that the correct pipe is selected and ready for data. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * * \return Signed 24-bit audio sample from the audio interface. */ static inline int32_t Audio_Host_ReadSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline int32_t Audio_Host_ReadSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo) { int32_t Sample; (void)AudioInterfaceInfo; Sample = (((uint32_t)Pipe_Read_8() << 16) | Pipe_Read_16_LE()); if (!(Pipe_BytesInPipe()))  Dean Camera committed Jun 09, 2011 310 311 312 313 314  { Pipe_Unfreeze(); Pipe_ClearIN(); Pipe_Freeze(); }  Dean Camera committed Jun 08, 2011 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333  return Sample; } /** Writes the next 8-bit audio sample to the current audio interface. * * \pre This should be preceded immediately by a call to the \ref Audio_Host_IsReadyForNextSample() function to * ensure that the correct pipe is selected and ready for data. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * \param[in] Sample Signed 8-bit audio sample. */ static inline void Audio_Host_WriteSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const int8_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline void Audio_Host_WriteSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const int8_t Sample) { Pipe_Write_8(Sample);  Dean Camera committed Jun 12, 2011 334  if (!(Pipe_IsReadWriteAllowed()))  Dean Camera committed Jun 09, 2011 335 336 337  { Pipe_Unfreeze(); Pipe_ClearOUT();  Dean Camera committed Jun 12, 2011 338  Pipe_WaitUntilReady();  Dean Camera committed Jun 09, 2011 339 340  Pipe_Freeze(); }  Dean Camera committed Jun 08, 2011 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357  } /** Writes the next 16-bit audio sample to the current audio interface. * * \pre This should be preceded immediately by a call to the \ref Audio_Host_IsReadyForNextSample() function to * ensure that the correct pipe is selected and ready for data. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * \param[in] Sample Signed 16-bit audio sample. */ static inline void Audio_Host_WriteSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const int16_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline void Audio_Host_WriteSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const int16_t Sample) { Pipe_Write_16_LE(Sample);  Dean Camera committed Jun 12, 2011 358  if (!(Pipe_IsReadWriteAllowed()))  Dean Camera committed Jun 09, 2011 359 360 361  { Pipe_Unfreeze(); Pipe_ClearOUT();  Dean Camera committed Jun 12, 2011 362  Pipe_WaitUntilReady();  Dean Camera committed Jun 09, 2011 363 364  Pipe_Freeze(); }  Dean Camera committed Jun 08, 2011 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382  } /** Writes the next 24-bit audio sample to the current audio interface. * * \pre This should be preceded immediately by a call to the \ref Audio_Host_IsReadyForNextSample() function to * ensure that the correct pipe is selected and ready for data. * * \param[in,out] AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state. * \param[in] Sample Signed 24-bit audio sample. */ static inline void Audio_Host_WriteSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const int32_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE; static inline void Audio_Host_WriteSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo, const int32_t Sample) { Pipe_Write_16_LE(Sample); Pipe_Write_8(Sample >> 16);  Dean Camera committed Jun 12, 2011 383  if (!(Pipe_IsReadWriteAllowed()))  Dean Camera committed Jun 09, 2011 384 385 386  { Pipe_Unfreeze(); Pipe_ClearOUT();  Dean Camera committed Jun 12, 2011 387  Pipe_WaitUntilReady();  Dean Camera committed Jun 09, 2011 388 389  Pipe_Freeze(); }  Dean Camera committed Jun 08, 2011 390 391 392 393 394 395  } /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Function Prototypes: */ #if defined(__INCLUDE_FROM_AUDIO_HOST_C)  Dean Camera committed Jun 14, 2011 396 397 398  static uint8_t DCOMP_Audio_Host_NextAudioControlInterface(void* CurrentDescriptor); static uint8_t DCOMP_Audio_Host_NextAudioStreamInterface(void* CurrentDescriptor); static uint8_t DCOMP_Audio_Host_NextAudioInterfaceDataEndpoint(void* CurrentDescriptor);  Dean Camera committed Jun 08, 2011 399 400 401 402 403 404 405 406 407 408 409 410  #endif #endif /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif #endif /** @} */