Reduce struct name pollution - group typedef struct names by class driver name where...
[pub/USBasp.git] / LUFA / Drivers / USB / Class / Device / Audio.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2009.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, and distribute this software
13 and its documentation for any purpose and without fee is hereby
14 granted, provided that the above copyright notice appear in all
15 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 /** \ingroup Group_USBClassAudio
32 * @defgroup Group_USBClassAudioDevice Audio Class Device Mode Driver
33 *
34 * \section Module Description
35 * Device Mode USB Class driver framework interface, for the Audio USB Class driver.
36 *
37 * @{
38 */
39
40 #ifndef _AUDIO_CLASS_DEVICE_H_
41 #define _AUDIO_CLASS_DEVICE_H_
42
43 /* Includes: */
44 #include "../../USB.h"
45 #include "../Common/Audio.h"
46
47 #include <string.h>
48
49 /* Enable C linkage for C++ Compilers: */
50 #if defined(__cplusplus)
51 extern "C" {
52 #endif
53
54 /* Public Interface - May be used in end-application: */
55 /* Type Defines: */
56 /** Class state structure. An instance of this structure should be made for each Audio interface
57 * within the user application, and passed to each of the Audio class driver functions as the
58 * AudioInterfaceInfo parameter. This stores each Audio interface's configuration and state information.
59 */
60 typedef struct
61 {
62 const struct
63 {
64 uint8_t StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this
65 * structure controls.
66 */
67
68 uint8_t DataINEndpointNumber; /**< Endpoint number of the incomming Audio Streaming data, if available
69 * (zero if unused).
70 */
71 uint16_t DataINEndpointSize; /**< Size in bytes of the incomming Audio Streaming data endpoint, if available
72 * (zero if unused).
73 */
74
75 uint8_t DataOUTEndpointNumber; /**< Endpoint number of the outgoing Audio Streaming data, if available
76 * (zero if unused).
77 */
78 uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing Audio Streaming data endpoint, if available
79 * (zero if unused).
80 */
81 } Config; /**< Config data for the USB class interface within the device. All elements in this section
82 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
83 */
84 struct
85 {
86 bool InterfaceEnabled; /**< Set and cleared by the class driver to indicate if the host has enabled the streaming endpoints
87 * of the Audio Streaming interface.
88 */
89 } State; /**< State data for the USB class interface within the device. All elements in this section
90 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
91 * the interface is enumerated.
92 */
93 } USB_ClassInfo_Audio_Device_t;
94
95 /* Function Prototypes: */
96 /** Configures the endpoints of a given Audio interface, ready for use. This should be linked to the library
97 * \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration containing the
98 * given Audio interface is selected.
99 *
100 * \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
101 *
102 * \return Boolean true if the endpoints were sucessfully configured, false otherwise
103 */
104 bool Audio_Device_ConfigureEndpoints(USB_ClassInfo_Audio_Device_t* AudioInterfaceInfo);
105
106 /** Processes incomming control requests from the host, that are directed to the given Audio class interface. This should be
107 * linked to the library \ref EVENT_USB_UnhandledControlPacket() event.
108 *
109 * \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
110 */
111 void Audio_Device_ProcessControlPacket(USB_ClassInfo_Audio_Device_t* AudioInterfaceInfo);
112
113 /** General management task for a given Audio class interface, required for the correct operation of the interface. This should
114 * be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
115 *
116 * \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
117 */
118 void Audio_Device_USBTask(USB_ClassInfo_Audio_Device_t* AudioInterfaceInfo);
119
120 /** Reads the next 8-bit audio sample from the current audio interface.
121 *
122 * \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
123 * the correct endpoint is selected and ready for data.
124 *
125 * \return Signed 8-bit audio sample from the audio interface
126 */
127 int8_t Audio_Device_ReadSample8(void);
128
129 /** Reads the next 16-bit audio sample from the current audio interface.
130 *
131 * \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
132 * the correct endpoint is selected and ready for data.
133 *
134 * \return Signed 16-bit audio sample from the audio interface
135 */
136 int16_t Audio_Device_ReadSample16(void);
137
138 /** Reads the next 24-bit audio sample from the current audio interface.
139 *
140 * \note This should be preceeded immediately by a call to the USB_Audio_IsSampleReceived() function to ensure that
141 * the correct endpoint is selected and ready for data.
142 *
143 * \return Signed 24-bit audio sample from the audio interface
144 */
145 int32_t Audio_Device_ReadSample24(void);
146
147 /** Writes the next 8-bit audio sample to the current audio interface.
148 *
149 * \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
150 * the correct endpoint is selected and ready for data.
151 *
152 * \param Sample Signed 8-bit audio sample
153 */
154 void Audio_Device_WriteSample8(int8_t Sample);
155
156 /** Writes the next 16-bit audio sample to the current audio interface.
157 *
158 * \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
159 * the correct endpoint is selected and ready for data.
160 *
161 * \param Sample Signed 16-bit audio sample
162 */
163 void Audio_Device_WriteSample16(int16_t Sample);
164
165 /** Writes the next 24-bit audio sample to the current audio interface.
166 *
167 * \note This should be preceeded immediately by a call to the USB_Audio_IsReadyForNextSample() function to ensure that
168 * the correct endpoint is selected and ready for data.
169 *
170 * \param Sample Signed 24-bit audio sample
171 */
172 void Audio_Device_WriteSample24(int32_t Sample);
173
174 /** Determines if the given audio interface is ready for a sample to be read from it.
175 *
176 * \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
177 *
178 * \return Boolean true if the given Audio interface has a sample to be read, false otherwise
179 */
180 bool Audio_Device_IsSampleReceived(USB_ClassInfo_Audio_Device_t* AudioInterfaceInfo);
181
182 /** Determines if the given audio interface is ready to accept the next sample to be written to it.
183 *
184 * \param AudioInterfaceInfo Pointer to a structure containing an Audio Class configuration and state.
185 *
186 * \return Boolean true if the given Audio interface is ready to accept the next sample, false otherwise
187 */
188 bool Audio_Device_IsReadyForNextSample(USB_ClassInfo_Audio_Device_t* AudioInterfaceInfo);
189
190 /* Disable C linkage for C++ Compilers: */
191 #if defined(__cplusplus)
192 }
193 #endif
194
195 #endif
196
197 /** @} */