Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / USB / Class / Host / Audio.h @ 978b99e5

History | View | Annotate | Download (19.4 KB)

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 Host mode driver for the library USB Audio 1.0 Class driver.
33
 *
34
 *  Host 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_USBClassAudioHost Audio 1.0 Class Host 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/Host/Audio.c <i>(Makefile source module name: LUFA_SRC_USBCLASS)</i>
46
 *
47
 *  \section Sec_ModDescription Module Description
48
 *  Host Mode USB Class driver framework interface, for the Audio 1.0 USB Class driver.
49
 *
50
 *  @{
51
 */
52

    
53
#ifndef __AUDIO_CLASS_HOST_H__
54
#define __AUDIO_CLASS_HOST_H__
55

    
56
        /* Includes: */
57
                #include "../../USB.h"
58
                #include "../Common/Audio.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/USB.h instead.
68
                #endif
69

    
70
        /* Public Interface - May be used in end-application: */
71
                /* Type Defines: */
72
                        /** \brief Audio Class Host Mode Configuration and State Structure.
73
                         *
74
                         *  Class state structure. An instance of this structure should be made within the user application,
75
                         *  and passed to each of the Audio class driver functions as the \c AudioInterfaceInfo parameter. This
76
                         *  stores each Audio interface's configuration and state information.
77
                         */
78
                        typedef struct
79
                        {
80
                                const struct
81
                                {
82
                                        uint8_t  DataINPipeNumber; /**< Pipe number of the Audio interface's IN data pipe. If this interface should not
83
                                                                    *   bind to an IN endpoint, this may be set to 0 to disable audio input streaming for
84
                                                                    *   this driver instance.
85
                                                                    */
86
                                        uint8_t  DataOUTPipeNumber; /**< Pipe number of the Audio interface's OUT data pipe. If this interface should not
87
                                                                    *   bind to an OUT endpoint, this may be set to 0 to disable audio output streaming for
88
                                                                    *   this driver instance.
89
                                                                    */
90
                                } Config; /**< Config data for the USB class interface within the device. All elements in this section
91
                                           *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.
92
                                           */
93
                                struct
94
                                {
95
                                        bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
96
                                                        *   after \ref Audio_Host_ConfigurePipes() is called and the Host state machine is in the
97
                                                        *   Configured state.
98
                                                        */
99
                                        uint8_t ControlInterfaceNumber; /**< Interface index of the Audio Control interface within the attached device. */
100
                                        uint8_t StreamingInterfaceNumber; /**< Interface index of the Audio Streaming interface within the attached device. */
101
                                        
102
                                        uint8_t EnabledStreamingAltIndex; /**< Alternative setting index of the Audio Streaming interface when the stream is enabled. */
103

    
104
                                        uint16_t DataINPipeSize; /**< Size in bytes of the Audio interface's IN data pipe. */
105
                                        uint16_t DataOUTPipeSize;  /**< Size in bytes of the Audio interface's OUT data pipe. */
106
                                } State; /**< State data for the USB class interface within the device. All elements in this section
107
                                                  *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when
108
                                                  *   the interface is enumerated.
109
                                                  */
110
                        } USB_ClassInfo_Audio_Host_t;
111

    
112
                /* Enums: */
113
                        /** Enum for the possible error codes returned by the \ref Audio_Host_ConfigurePipes() function. */
114
                        enum AUDIO_Host_EnumerationFailure_ErrorCodes_t
115
                        {
116
                                AUDIO_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully. */
117
                                AUDIO_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor. */
118
                                AUDIO_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible AUDIO interface was not found in the device's Configuration Descriptor. */
119
                                AUDIO_ENUMERROR_PipeConfigurationFailed    = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
120
                        };
121

    
122
                /* Function Prototypes: */
123
                        /** Host interface configuration routine, to configure a given Audio host interface instance using the Configuration
124
                         *  Descriptor read from an attached USB device. This function automatically updates the given Audio Host instance's
125
                         *  state values and configures the pipes required to communicate with the interface if it is found within the
126
                         *  device. This should be called once after the stack has enumerated the attached device, while the host state
127
                         *  machine is in the Addressed state.
128
                         *
129
                         *  \param[in,out] AudioInterfaceInfo      Pointer to a structure containing an Audio Class host configuration and state.
130
                         *  \param[in]     ConfigDescriptorSize    Length of the attached device's Configuration Descriptor.
131
                         *  \param[in]     DeviceConfigDescriptor  Pointer to a buffer containing the attached device's Configuration Descriptor.
132
                         *
133
                         *  \return A value from the \ref AUDIO_Host_EnumerationFailure_ErrorCodes_t enum.
134
                         */
135
                        uint8_t Audio_Host_ConfigurePipes(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
136
                                                          uint16_t ConfigDescriptorSize,
137
                                                          void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
138

    
139
                        /** Starts or stops the audio streaming for the given configured Audio Host interface, allowing for audio samples to be
140
                         *  send and/or received.
141
                         *
142
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class host configuration and state.
143
                         *  \param[in]     EnableStreaming     Boolean true to enable streaming of the specified interface, false to disable
144
                         *
145
                         *  \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.
146
                         */
147
                        uint8_t Audio_Host_StartStopStreaming(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
148
                                                              const bool EnableStreaming) ATTR_NON_NULL_PTR_ARG(1);
149

    
150
                        /** Gets or sets the specified property of a streaming audio class endpoint that is bound to a pipe in the given
151
                         *  class instance.
152
                         *
153
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class host configuration and state.
154
                         *  \param[in]     DataPipeIndex       Index of the data pipe whose bound endpoint is to be altered.
155
                         *  \param[in]     EndpointProperty    Property of the endpoint to get or set, a value from \ref Audio_ClassRequests_t.
156
                         *  \param[in]     EndpointControl     Parameter of the endpoint to get or set, a value from \ref Audio_EndpointControls_t.
157
                         *  \param[in,out] DataLength          For SET operations, the length of the parameter data to set. For GET operations, the maximum
158
                         *                                     length of the retrieved data.
159
                         *  \param[in,out] Data                Pointer to a location where the parameter data is stored for SET operations, or where
160
                         *                                     the retrieved data is to be stored for GET operations.
161
                         *
162
                         *  \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.
163
                         */
164
                        uint8_t Audio_Host_GetSetEndpointProperty(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
165
                                                                  const uint8_t DataPipeIndex,
166
                                                                  const uint8_t EndpointProperty,
167
                                                                  const uint8_t EndpointControl,
168
                                                                  const uint16_t DataLength,
169
                                                                  void* const Data) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6);
170

    
171
                /* Inline Functions: */
172
                        /** General management task for a given Audio host class interface, required for the correct operation of
173
                         *  the interface. This should be called frequently in the main program loop, before the master USB management task
174
                         *  \ref USB_USBTask().
175
                         *
176
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class host configuration and state.
177
                         */
178
                        static inline void Audio_Host_USBTask(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
179
                                                              ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
180
                        static inline void Audio_Host_USBTask(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
181
                        {
182
                                (void)AudioInterfaceInfo;
183
                        }
184

    
185
                        /** Determines if the given audio interface is ready for a sample to be read from it, and selects the streaming
186
                         *  IN pipe ready for reading.
187
                         *
188
                         *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or
189
                         *       the call will fail.
190
                         *
191
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
192
                         *
193
                         *  \return Boolean \c true if the given Audio interface has a sample to be read, \c false otherwise.
194
                         */
195
                        static inline bool Audio_Host_IsSampleReceived(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
196
                                                                       ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
197
                        static inline bool Audio_Host_IsSampleReceived(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
198
                        {
199
                                if ((USB_HostState != HOST_STATE_Configured) || !(AudioInterfaceInfo->State.IsActive))
200
                                  return false;
201

    
202
                                bool SampleReceived = false;
203

    
204
                                Pipe_SelectPipe(AudioInterfaceInfo->Config.DataINPipeNumber);
205
                                Pipe_Unfreeze();
206
                                SampleReceived = Pipe_IsINReceived();
207
                                Pipe_Freeze();
208

    
209
                                return SampleReceived;
210
                        }
211

    
212
                        /** Determines if the given audio interface is ready to accept the next sample to be written to it, and selects
213
                         *  the streaming OUT pipe ready for writing.
214
                         *
215
                         *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or
216
                         *       the call will fail.
217
                         *
218
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
219
                         *
220
                         *  \return Boolean \c true if the given Audio interface is ready to accept the next sample, \c false otherwise.
221
                         */
222
                        static inline bool Audio_Host_IsReadyForNextSample(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
223
                                                                           ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
224
                        static inline bool Audio_Host_IsReadyForNextSample(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
225
                        {
226
                                if ((USB_HostState != HOST_STATE_Configured) || !(AudioInterfaceInfo->State.IsActive))
227
                                  return false;
228

    
229
                                Pipe_SelectPipe(AudioInterfaceInfo->Config.DataOUTPipeNumber);
230
                                return Pipe_IsOUTReady();
231
                        }
232

    
233
                        /** Reads the next 8-bit audio sample from the current audio interface.
234
                         *
235
                         *  \pre This should be preceded immediately by a call to the \ref Audio_Host_IsSampleReceived() function to ensure
236
                         *       that the correct pipe is selected and ready for data.
237
                         *
238
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
239
                         *
240
                         *  \return  Signed 8-bit audio sample from the audio interface.
241
                         */
242
                        static inline int8_t Audio_Host_ReadSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
243
                                                                    ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
244
                        static inline int8_t Audio_Host_ReadSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
245
                        {
246
                                int8_t Sample;
247

    
248
                                (void)AudioInterfaceInfo;
249

    
250
                                Sample = Pipe_Read_8();
251

    
252
                                if (!(Pipe_BytesInPipe()))
253
                                {
254
                                        Pipe_Unfreeze();
255
                                        Pipe_ClearIN();
256
                                        Pipe_Freeze();
257
                                }
258

    
259
                                return Sample;
260
                        }
261

    
262
                        /** Reads the next 16-bit audio sample from the current audio interface.
263
                         *
264
                         *  \pre This should be preceded immediately by a call to the \ref Audio_Host_IsSampleReceived() function to ensure
265
                         *       that the correct pipe is selected and ready for data.
266
                         *
267
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
268
                         *
269
                         *  \return  Signed 16-bit audio sample from the audio interface.
270
                         */
271
                        static inline int16_t Audio_Host_ReadSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
272
                                                                      ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
273
                        static inline int16_t Audio_Host_ReadSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
274
                        {
275
                                int16_t Sample;
276

    
277
                                (void)AudioInterfaceInfo;
278

    
279
                                Sample = (int16_t)Pipe_Read_16_LE();
280

    
281
                                if (!(Pipe_BytesInPipe()))
282
                                {
283
                                        Pipe_Unfreeze();
284
                                        Pipe_ClearIN();
285
                                        Pipe_Freeze();
286
                                }
287

    
288
                                return Sample;
289
                        }
290

    
291
                        /** Reads the next 24-bit audio sample from the current audio interface.
292
                         *
293
                         *  \pre This should be preceded immediately by a call to the \ref Audio_Host_IsSampleReceived() function to ensure
294
                         *       that the correct pipe is selected and ready for data.
295
                         *
296
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
297
                         *
298
                         *  \return Signed 24-bit audio sample from the audio interface.
299
                         */
300
                        static inline int32_t Audio_Host_ReadSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
301
                                                                      ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
302
                        static inline int32_t Audio_Host_ReadSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo)
303
                        {
304
                                int32_t Sample;
305

    
306
                                (void)AudioInterfaceInfo;
307

    
308
                                Sample = (((uint32_t)Pipe_Read_8() << 16) | Pipe_Read_16_LE());
309

    
310
                                if (!(Pipe_BytesInPipe()))
311
                                {
312
                                        Pipe_Unfreeze();
313
                                        Pipe_ClearIN();
314
                                        Pipe_Freeze();
315
                                }
316

    
317
                                return Sample;
318
                        }
319

    
320
                        /** Writes the next 8-bit audio sample to the current audio interface.
321
                         *
322
                         *  \pre This should be preceded immediately by a call to the \ref Audio_Host_IsReadyForNextSample() function to
323
                         *       ensure that the correct pipe is selected and ready for data.
324
                         *
325
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
326
                         *  \param[in]     Sample              Signed 8-bit audio sample.
327
                         */
328
                        static inline void Audio_Host_WriteSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
329
                                                                   const int8_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
330
                        static inline void Audio_Host_WriteSample8(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
331
                                                                   const int8_t Sample)
332
                        {
333
                                (void)AudioInterfaceInfo;
334
                        
335
                                Pipe_Write_8(Sample);
336

    
337
                                if (!(Pipe_IsReadWriteAllowed()))
338
                                {
339
                                        Pipe_Unfreeze();
340
                                        Pipe_ClearOUT();
341
                                        Pipe_WaitUntilReady();
342
                                        Pipe_Freeze();
343
                                }
344
                        }
345

    
346
                        /** Writes the next 16-bit audio sample to the current audio interface.
347
                         *
348
                         *  \pre This should be preceded immediately by a call to the \ref Audio_Host_IsReadyForNextSample() function to
349
                         *       ensure that the correct pipe is selected and ready for data.
350
                         *
351
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
352
                         *  \param[in]     Sample              Signed 16-bit audio sample.
353
                         */
354
                        static inline void Audio_Host_WriteSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
355
                                                                    const int16_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
356
                        static inline void Audio_Host_WriteSample16(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
357
                                                                    const int16_t Sample)
358
                        {
359
                                (void)AudioInterfaceInfo;
360
                        
361
                                Pipe_Write_16_LE(Sample);
362

    
363
                                if (!(Pipe_IsReadWriteAllowed()))
364
                                {
365
                                        Pipe_Unfreeze();
366
                                        Pipe_ClearOUT();
367
                                        Pipe_WaitUntilReady();
368
                                        Pipe_Freeze();
369
                                }
370
                        }
371

    
372
                        /** Writes the next 24-bit audio sample to the current audio interface.
373
                         *
374
                         *  \pre This should be preceded immediately by a call to the \ref Audio_Host_IsReadyForNextSample() function to
375
                         *       ensure that the correct pipe is selected and ready for data.
376
                         *
377
                         *  \param[in,out] AudioInterfaceInfo  Pointer to a structure containing an Audio Class configuration and state.
378
                         *  \param[in]     Sample              Signed 24-bit audio sample.
379
                         */
380
                        static inline void Audio_Host_WriteSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
381
                                                                    const int32_t Sample) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
382
                        static inline void Audio_Host_WriteSample24(USB_ClassInfo_Audio_Host_t* const AudioInterfaceInfo,
383
                                                                    const int32_t Sample)
384
                        {
385
                                (void)AudioInterfaceInfo;
386

    
387
                                Pipe_Write_16_LE(Sample);
388
                                Pipe_Write_8(Sample >> 16);
389

    
390
                                if (!(Pipe_IsReadWriteAllowed()))
391
                                {
392
                                        Pipe_Unfreeze();
393
                                        Pipe_ClearOUT();
394
                                        Pipe_WaitUntilReady();
395
                                        Pipe_Freeze();
396
                                }
397
                        }
398
                        
399
        /* Private Interface - For use in library only: */
400
        #if !defined(__DOXYGEN__)
401
                /* Function Prototypes: */
402
                        #if defined(__INCLUDE_FROM_AUDIO_HOST_C)
403
                                static uint8_t DCOMP_Audio_Host_NextAudioControlInterface(void* CurrentDescriptor)
404
                                                                                          ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
405
                                static uint8_t DCOMP_Audio_Host_NextAudioStreamInterface(void* CurrentDescriptor)
406
                                                                                         ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
407
                                static uint8_t DCOMP_Audio_Host_NextAudioInterfaceDataEndpoint(void* CurrentDescriptor)
408
                                                                                               ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
409
                        #endif
410
        #endif
411

    
412
        /* Disable C linkage for C++ Compilers: */
413
                #if defined(__cplusplus)
414
                        }
415
                #endif
416

    
417
#endif
418

    
419
/** @} */
420