Line data Source code
1 1 : /*
2 : * USB audio class core header
3 : *
4 : * Copyright (c) 2020 Nordic Semiconductor ASA
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : /**
10 : * @file
11 : * @brief USB Audio Device Class public header
12 : *
13 : * Header follows below documentation:
14 : * - USB Device Class Definition for Audio Devices (audio10.pdf)
15 : *
16 : * Additional documentation considered a part of USB Audio v1.0:
17 : * - USB Device Class Definition for Audio Data Formats (frmts10.pdf)
18 : * - USB Device Class Definition for Terminal Types (termt10.pdf)
19 : */
20 :
21 : #ifndef ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_
22 : #define ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_
23 :
24 : #include <zephyr/usb/usb_ch9.h>
25 : #include <zephyr/device.h>
26 : #include <zephyr/net_buf.h>
27 : #include <zephyr/sys/util.h>
28 :
29 : /** Audio Interface Subclass Codes.
30 : * Refer to Table A-2 from audio10.pdf
31 : */
32 0 : enum usb_audio_int_subclass_codes {
33 : USB_AUDIO_SUBCLASS_UNDEFINED = 0x00,
34 : USB_AUDIO_AUDIOCONTROL = 0x01,
35 : USB_AUDIO_AUDIOSTREAMING = 0x02,
36 : USB_AUDIO_MIDISTREAMING = 0x03
37 : };
38 :
39 : /** Audio Class-Specific AC Interface Descriptor Subtypes.
40 : * Refer to Table A-5 from audio10.pdf
41 : */
42 0 : enum usb_audio_cs_ac_int_desc_subtypes {
43 : USB_AUDIO_AC_DESCRIPTOR_UNDEFINED = 0x00,
44 : USB_AUDIO_HEADER = 0x01,
45 : USB_AUDIO_INPUT_TERMINAL = 0x02,
46 : USB_AUDIO_OUTPUT_TERMINAL = 0x03,
47 : USB_AUDIO_MIXER_UNIT = 0x04,
48 : USB_AUDIO_SELECTOR_UNIT = 0x05,
49 : USB_AUDIO_FEATURE_UNIT = 0x06,
50 : USB_AUDIO_PROCESSING_UNIT = 0x07,
51 : USB_AUDIO_EXTENSION_UNIT = 0x08
52 : };
53 :
54 : /** Audio Class-Specific AS Interface Descriptor Subtypes
55 : * Refer to Table A-6 from audio10.pdf
56 : */
57 0 : enum usb_audio_cs_as_int_desc_subtypes {
58 : USB_AUDIO_AS_DESCRIPTOR_UNDEFINED = 0x00,
59 : USB_AUDIO_AS_GENERAL = 0x01,
60 : USB_AUDIO_FORMAT_TYPE = 0x02,
61 : USB_AUDIO_FORMAT_SPECIFIC = 0x03
62 : };
63 :
64 : /** Audio Class-Specific Request Codes
65 : * Refer to Table A-9 from audio10.pdf
66 : */
67 0 : enum usb_audio_cs_req_codes {
68 : USB_AUDIO_REQUEST_CODE_UNDEFINED = 0x00,
69 : USB_AUDIO_SET_CUR = 0x01,
70 : USB_AUDIO_GET_CUR = 0x81,
71 : USB_AUDIO_SET_MIN = 0x02,
72 : USB_AUDIO_GET_MIN = 0x82,
73 : USB_AUDIO_SET_MAX = 0x03,
74 : USB_AUDIO_GET_MAX = 0x83,
75 : USB_AUDIO_SET_RES = 0x04,
76 : USB_AUDIO_GET_RES = 0x84,
77 : USB_AUDIO_SET_MEM = 0x05,
78 : USB_AUDIO_GET_MEM = 0x85,
79 : USB_AUDIO_GET_STAT = 0xFF
80 : };
81 :
82 : /** Feature Unit Control Selectors
83 : * Refer to Table A-11 from audio10.pdf
84 : */
85 0 : enum usb_audio_fucs {
86 : USB_AUDIO_FU_CONTROL_UNDEFINED = 0x00,
87 : USB_AUDIO_FU_MUTE_CONTROL = 0x01,
88 : USB_AUDIO_FU_VOLUME_CONTROL = 0x02,
89 : USB_AUDIO_FU_BASS_CONTROL = 0x03,
90 : USB_AUDIO_FU_MID_CONTROL = 0x04,
91 : USB_AUDIO_FU_TREBLE_CONTROL = 0x05,
92 : USB_AUDIO_FU_GRAPHIC_EQUALIZER_CONTROL = 0x06,
93 : USB_AUDIO_FU_AUTOMATIC_GAIN_CONTROL = 0x07,
94 : USB_AUDIO_FU_DELAY_CONTROL = 0x08,
95 : USB_AUDIO_FU_BASS_BOOST_CONTROL = 0x09,
96 : USB_AUDIO_FU_LOUDNESS_CONTROL = 0x0A
97 : };
98 :
99 : /** USB Terminal Types
100 : * Refer to Table 2-1 - Table 2-4 from termt10.pdf
101 : */
102 1 : enum usb_audio_terminal_types {
103 : /**
104 : * @name USB Terminal Types
105 : * @{
106 : */
107 : /** USB undefined */
108 : USB_AUDIO_USB_UNDEFINED = 0x0100,
109 : /** USB streaming */
110 : USB_AUDIO_USB_STREAMING = 0x0101,
111 : /** USB vendor specific */
112 : USB_AUDIO_USB_VENDOR_SPEC = 0x01FF,
113 : /** @} */
114 :
115 : /**
116 : * @name Input Terminal Types
117 : * @{
118 : */
119 : /** Input undefined */
120 : USB_AUDIO_IN_UNDEFINED = 0x0200,
121 : /** Microphone */
122 : USB_AUDIO_IN_MICROPHONE = 0x0201,
123 : /** Desktop microphone */
124 : USB_AUDIO_IN_DESKTOP_MIC = 0x0202,
125 : /** Personal microphone */
126 : USB_AUDIO_IN_PERSONAL_MIC = 0x0203,
127 : /** Omni directional microphone */
128 : USB_AUDIO_IN_OM_DIR_MIC = 0x0204,
129 : /** Microphone array */
130 : USB_AUDIO_IN_MIC_ARRAY = 0x0205,
131 : /** Processing microphone array */
132 : USB_AUDIO_IN_PROC_MIC_ARRAY = 0x0205,
133 : /** @} */
134 :
135 : /**
136 : * @name Output Terminal Types
137 : * @{
138 : */
139 : /** Output undefined */
140 : USB_AUDIO_OUT_UNDEFINED = 0x0300,
141 : /** Speaker */
142 : USB_AUDIO_OUT_SPEAKER = 0x0301,
143 : /** Headphones */
144 : USB_AUDIO_OUT_HEADPHONES = 0x0302,
145 : /** Head mounted display audio */
146 : USB_AUDIO_OUT_HEAD_AUDIO = 0x0303,
147 : /** Desktop speaker */
148 : USB_AUDIO_OUT_DESKTOP_SPEAKER = 0x0304,
149 : /** Room speaker */
150 : USB_AUDIO_OUT_ROOM_SPEAKER = 0x0305,
151 : /** Communication speaker */
152 : USB_AUDIO_OUT_COMM_SPEAKER = 0x0306,
153 : /** Low frequency effects speaker */
154 : USB_AUDIO_OUT_LOW_FREQ_SPEAKER = 0x0307,
155 : /** @} */
156 :
157 : /**
158 : * @name Bi-directional Terminal Types
159 : * @{
160 : */
161 : /** Bidirectional undefined */
162 : USB_AUDIO_IO_UNDEFINED = 0x0400,
163 : /** Handset */
164 : USB_AUDIO_IO_HANDSET = 0x0401,
165 : /** Headset */
166 : USB_AUDIO_IO_HEADSET = 0x0402,
167 : /** Speakerphone, no echo reduction */
168 : USB_AUDIO_IO_SPEAKERPHONE_ECHO_NONE = 0x0403,
169 : /** Speakerphone, echo reduction */
170 : USB_AUDIO_IO_SPEAKERPHONE_ECHO_SUP = 0x0404,
171 : /** Speakerphone, echo cancellation */
172 : USB_AUDIO_IO_SPEAKERPHONE_ECHO_CAN = 0x0405,
173 : };
174 :
175 : /**
176 : * @brief Audio device direction.
177 : */
178 0 : enum usb_audio_direction {
179 : USB_AUDIO_IN = 0x00,
180 : USB_AUDIO_OUT = 0x01
181 : };
182 :
183 : /**
184 : * @brief Feature Unit event structure.
185 : *
186 : * The event structure is used by feature_update_cb in order to inform the App
187 : * whenever the Host has modified one of the device features.
188 : */
189 1 : struct usb_audio_fu_evt {
190 : /**
191 : * The device direction that has been changed.
192 : * Applicable for Headset device only.
193 : */
194 1 : enum usb_audio_direction dir;
195 : /** Control selector feature that has been changed. */
196 1 : enum usb_audio_fucs cs;
197 : /**
198 : * Device channel that has been changed.
199 : * If 0xFF, then all channels have been changed.
200 : */
201 1 : uint8_t channel;
202 : /** Length of the val field. */
203 1 : uint8_t val_len;
204 : /** Value of the feature that has been set. */
205 1 : const void *val;
206 : };
207 :
208 : /**
209 : * @brief Callback type used to inform the app that data were requested
210 : * from the device and may be send to the Host.
211 : * For sending the data usb_audio_send() API function should be used.
212 : *
213 : * @note User may not use this callback and may try to send in 1ms task
214 : * instead. Sending every 1ms may be unsuccessful and may return -EAGAIN
215 : * if Host did not required data.
216 : *
217 : * @param dev The device for which data were requested by the Host.
218 : */
219 1 : typedef void (*usb_audio_data_request_cb_t)(const struct device *dev);
220 :
221 : /**
222 : * @brief Callback type used to inform the app that data were successfully
223 : * send/received.
224 : *
225 : * @param dev The device for which the callback was called.
226 : * @param buffer Pointer to the net_buf data chunk that was successfully
227 : * send/received. If the application uses data_written_cb and/or
228 : * data_received_cb callbacks it is responsible for freeing the
229 : * buffer by itself.
230 : * @param size Amount of data that were successfully send/received.
231 : */
232 1 : typedef void (*usb_audio_data_completion_cb_t)(const struct device *dev,
233 : struct net_buf *buffer,
234 : size_t size);
235 :
236 : /**
237 : * @brief Callback type used to inform the app that Host has changed
238 : * one of the features configured for the device.
239 : * Applicable for all devices.
240 : *
241 : * @warning Host may not use all of configured features.
242 : *
243 : * @param dev USB Audio device
244 : * @param evt Pointer to an event to be parsed by the App.
245 : * Pointer struct is temporary and is valid only during the
246 : * execution of this callback.
247 : */
248 1 : typedef void (*usb_audio_feature_updated_cb_t)(const struct device *dev,
249 : const struct usb_audio_fu_evt *evt);
250 :
251 : /**
252 : * @brief Audio callbacks used to interact with audio devices by user App.
253 : *
254 : * usb_audio_ops structure contains all relevant callbacks to interact with
255 : * USB Audio devices. Each of this callbacks is optional and may be left NULL.
256 : * This will not break the stack but could make USB Audio device useless.
257 : * Depending on the device some of those callbacks are necessary to make USB
258 : * device work as expected sending/receiving data. For more information refer
259 : * to callback documentation above.
260 : */
261 1 : struct usb_audio_ops {
262 : /** Callback called when data could be send */
263 1 : usb_audio_data_request_cb_t data_request_cb;
264 :
265 : /** Callback called when data were successfully written with sending
266 : * capable device. Applicable for headset and microphone. Unused for
267 : * headphones.
268 : */
269 1 : usb_audio_data_completion_cb_t data_written_cb;
270 :
271 : /** Callback called when data were successfully received by receive
272 : * capable device. Applicable for headset and headphones. Unused for
273 : * microphone.
274 : */
275 1 : usb_audio_data_completion_cb_t data_received_cb;
276 :
277 : /** Callback called when features were modified by the Host */
278 1 : usb_audio_feature_updated_cb_t feature_update_cb;
279 : };
280 :
281 : /** @brief Get the frame size that is accepted by the Host.
282 : *
283 : * This function returns the frame size for Input Devices that is expected
284 : * by the Host. Returned value rely on Input Device configuration:
285 : * - number of channels
286 : * - sampling frequency
287 : * - sample resolution
288 : * Device configuration is done via DT overlay.
289 : *
290 : * @param dev The Input device that is asked for frame size.
291 : *
292 : * @warning Do not use with OUT only devices (Headphones).
293 : * For OUT only devices this function shall return 0.
294 : */
295 1 : size_t usb_audio_get_in_frame_size(const struct device *dev);
296 :
297 : /**
298 : * @brief Register the USB Audio device and make it usable.
299 : * This must be called in order to make the device work
300 : * and respond to all relevant requests.
301 : *
302 : * @param dev USB Audio device
303 : * @param ops USB audio callback structure. Callback are used to
304 : * inform the user about what is happening
305 : */
306 1 : void usb_audio_register(const struct device *dev,
307 : const struct usb_audio_ops *ops);
308 :
309 : /**
310 : * @brief Send data using USB Audio device
311 : *
312 : * @param dev USB Audio device which will send the data
313 : * over its ISO IN endpoint
314 : * @param buffer Pointer to the buffer that should be send. User is
315 : * responsible for managing the buffer for Input devices. In case
316 : * of sending error user must decide if the buffer should be
317 : * dropped or retransmitted.
318 : * After the buffer was sent successfully it is passed to the
319 : * data_written_cb callback if the application uses one or
320 : * automatically freed otherwise.
321 : * User must provide proper net_buf chunk especially when
322 : * it comes to its size. This information can be obtained
323 : * using usb_audio_get_in_frame_size() API function.
324 : *
325 : * @param len Length of the data to be send
326 : *
327 : * @return 0 on success, negative error on fail
328 : */
329 1 : int usb_audio_send(const struct device *dev, struct net_buf *buffer,
330 : size_t len);
331 :
332 : #endif /* ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_ */
|
