mikroSDK Reference Manual
audio_device.h
1/*
2 * The MIT License (MIT)
3 *
4 * Copyright (c) 2020 Ha Thach (tinyusb.org)
5 * Copyright (c) 2020 Reinhard Panhuber
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
23 * THE SOFTWARE.
24 *
25 * This file is part of the TinyUSB stack.
26 */
27
28#ifndef _TUSB_AUDIO_DEVICE_H_
29#define _TUSB_AUDIO_DEVICE_H_
30
31#include "audio.h"
32
33//--------------------------------------------------------------------+
34// Class Driver Configuration
35//--------------------------------------------------------------------+
36
37// All sizes are in bytes!
38
39#ifndef CFG_TUD_AUDIO_FUNC_1_DESC_LEN
40#error You must tell the driver the length of the audio function descriptor including IAD descriptor
41#endif
42#if CFG_TUD_AUDIO > 1
43#ifndef CFG_TUD_AUDIO_FUNC_2_DESC_LEN
44#error You must tell the driver the length of the audio function descriptor including IAD descriptor
45#endif
46#endif
47#if CFG_TUD_AUDIO > 2
48#ifndef CFG_TUD_AUDIO_FUNC_3_DESC_LEN
49#error You must tell the driver the length of the audio function descriptor including IAD descriptor
50#endif
51#endif
52
53// Number of Standard AS Interface Descriptors (4.9.1) defined per audio function - this is required to be able to remember the current alternate settings of these interfaces
54#ifndef CFG_TUD_AUDIO_FUNC_1_N_AS_INT
55#error You must tell the driver the number of Standard AS Interface Descriptors you have defined in the audio function descriptor!
56#endif
57#if CFG_TUD_AUDIO > 1
58#ifndef CFG_TUD_AUDIO_FUNC_2_N_AS_INT
59#error You must tell the driver the number of Standard AS Interface Descriptors you have defined in the audio function descriptor!
60#endif
61#endif
62#if CFG_TUD_AUDIO > 2
63#ifndef CFG_TUD_AUDIO_FUNC_3_N_AS_INT
64#error You must tell the driver the number of Standard AS Interface Descriptors you have defined in the audio function descriptor!
65#endif
66#endif
67
68// Size of control buffer used to receive and send control messages via EP0 - has to be big enough to hold your biggest request structure e.g. range requests with multiple intervals defined or cluster descriptors
69#ifndef CFG_TUD_AUDIO_FUNC_1_CTRL_BUF_SZ
70#error You must define an audio class control request buffer size!
71#endif
72
73#if CFG_TUD_AUDIO > 1
74#ifndef CFG_TUD_AUDIO_FUNC_2_CTRL_BUF_SZ
75#error You must define an audio class control request buffer size!
76#endif
77#endif
78
79#if CFG_TUD_AUDIO > 2
80#ifndef CFG_TUD_AUDIO_FUNC_3_CTRL_BUF_SZ
81#error You must define an audio class control request buffer size!
82#endif
83#endif
84
85// End point sizes IN BYTES - Limits: Full Speed <= 1023, High Speed <= 1024
86#ifndef CFG_TUD_AUDIO_ENABLE_EP_IN
87#define CFG_TUD_AUDIO_ENABLE_EP_IN 0 // TX
88#endif
89
90#ifndef CFG_TUD_AUDIO_ENABLE_EP_OUT
91#define CFG_TUD_AUDIO_ENABLE_EP_OUT 0 // RX
92#endif
93
94// Maximum EP sizes for all alternate AS interface settings - used for checks and buffer allocation
95#if CFG_TUD_AUDIO_ENABLE_EP_IN
96#ifndef CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX
97#error You must tell the driver the biggest EP IN size!
98#endif
99#if CFG_TUD_AUDIO > 1
100#ifndef CFG_TUD_AUDIO_FUNC_2_EP_IN_SZ_MAX
101#error You must tell the driver the biggest EP IN size!
102#endif
103#endif
104#if CFG_TUD_AUDIO > 2
105#ifndef CFG_TUD_AUDIO_FUNC_3_EP_IN_SZ_MAX
106#error You must tell the driver the biggest EP IN size!
107#endif
108#endif
109#endif // CFG_TUD_AUDIO_ENABLE_EP_IN
110
111#if CFG_TUD_AUDIO_ENABLE_EP_OUT
112#ifndef CFG_TUD_AUDIO_FUNC_1_EP_OUT_SZ_MAX
113#error You must tell the driver the biggest EP OUT size!
114#endif
115#if CFG_TUD_AUDIO > 1
116#ifndef CFG_TUD_AUDIO_FUNC_2_EP_OUT_SZ_MAX
117#error You must tell the driver the biggest EP OUT size!
118#endif
119#endif
120#if CFG_TUD_AUDIO > 2
121#ifndef CFG_TUD_AUDIO_FUNC_3_EP_OUT_SZ_MAX
122#error You must tell the driver the biggest EP OUT size!
123#endif
124#endif
125#endif // CFG_TUD_AUDIO_ENABLE_EP_OUT
126
127// Software EP FIFO buffer sizes - must be >= max EP SIZEs!
128#ifndef CFG_TUD_AUDIO_FUNC_1_EP_IN_SW_BUF_SZ
129#define CFG_TUD_AUDIO_FUNC_1_EP_IN_SW_BUF_SZ 0
130#endif
131#ifndef CFG_TUD_AUDIO_FUNC_2_EP_IN_SW_BUF_SZ
132#define CFG_TUD_AUDIO_FUNC_2_EP_IN_SW_BUF_SZ 0
133#endif
134#ifndef CFG_TUD_AUDIO_FUNC_3_EP_IN_SW_BUF_SZ
135#define CFG_TUD_AUDIO_FUNC_3_EP_IN_SW_BUF_SZ 0
136#endif
137
138#ifndef CFG_TUD_AUDIO_FUNC_1_EP_OUT_SW_BUF_SZ
139#define CFG_TUD_AUDIO_FUNC_1_EP_OUT_SW_BUF_SZ 0
140#endif
141#ifndef CFG_TUD_AUDIO_FUNC_2_EP_OUT_SW_BUF_SZ
142#define CFG_TUD_AUDIO_FUNC_2_EP_OUT_SW_BUF_SZ 0
143#endif
144#ifndef CFG_TUD_AUDIO_FUNC_3_EP_OUT_SW_BUF_SZ
145#define CFG_TUD_AUDIO_FUNC_3_EP_OUT_SW_BUF_SZ 0
146#endif
147
148#if CFG_TUD_AUDIO_ENABLE_EP_IN
149#if CFG_TUD_AUDIO_FUNC_1_EP_IN_SW_BUF_SZ < CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX
150#error EP software buffer size MUST BE at least as big as maximum EP size
151#endif
152
153#if CFG_TUD_AUDIO > 1
154#if CFG_TUD_AUDIO_FUNC_2_EP_IN_SW_BUF_SZ < CFG_TUD_AUDIO_FUNC_2_EP_IN_SZ_MAX
155#error EP software buffer size MUST BE at least as big as maximum EP size
156#endif
157#endif
158
159#if CFG_TUD_AUDIO > 2
160#if CFG_TUD_AUDIO_FUNC_3_EP_IN_SW_BUF_SZ < CFG_TUD_AUDIO_FUNC_3_EP_IN_SZ_MAX
161#error EP software buffer size MUST BE at least as big as maximum EP size
162#endif
163#endif
164#endif
165
166#if CFG_TUD_AUDIO_ENABLE_EP_OUT
167#if CFG_TUD_AUDIO_FUNC_1_EP_OUT_SW_BUF_SZ < CFG_TUD_AUDIO_FUNC_1_EP_OUT_SZ_MAX
168#error EP software buffer size MUST BE at least as big as maximum EP size
169#endif
170
171#if CFG_TUD_AUDIO > 1
172#if CFG_TUD_AUDIO_FUNC_2_EP_OUT_SW_BUF_SZ < CFG_TUD_AUDIO_FUNC_2_EP_OUT_SZ_MAX
173#error EP software buffer size MUST BE at least as big as maximum EP size
174#endif
175#endif
176
177#if CFG_TUD_AUDIO > 2
178#if CFG_TUD_AUDIO_FUNC_3_EP_OUT_SW_BUF_SZ < CFG_TUD_AUDIO_FUNC_3_EP_OUT_SZ_MAX
179#error EP software buffer size MUST BE at least as big as maximum EP size
180#endif
181#endif
182#endif
183
184// Enable/disable feedback EP (required for asynchronous RX applications)
185#ifndef CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP
186#define CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP 0 // Feedback - 0 or 1
187#endif
188
189// Enable/disable conversion from 16.16 to 10.14 format on full-speed devices. See tud_audio_n_fb_set().
190#ifndef CFG_TUD_AUDIO_ENABLE_FEEDBACK_FORMAT_CORRECTION
191#define CFG_TUD_AUDIO_ENABLE_FEEDBACK_FORMAT_CORRECTION 0 // 0 or 1
192#endif
193
194// Audio interrupt control EP size - disabled if 0
195#ifndef CFG_TUD_AUDIO_INT_CTR_EPSIZE_IN
196#define CFG_TUD_AUDIO_INT_CTR_EPSIZE_IN 0 // Audio interrupt control - if required - 6 Bytes according to UAC 2 specification (p. 74)
197#endif
198
199#ifndef CFG_TUD_AUDIO_INT_CTR_EP_IN_SW_BUFFER_SIZE
200#define CFG_TUD_AUDIO_INT_CTR_EP_IN_SW_BUFFER_SIZE 6 // Buffer size of audio control interrupt EP - 6 Bytes according to UAC 2 specification (p. 74)
201#endif
202
203// Use software encoding/decoding
204
205// The software coding feature of the driver is not mandatory. It is useful if, for instance, you have two I2S streams which need to be interleaved
206// into a single PCM stream as SAMPLE_1 | SAMPLE_2 | SAMPLE_3 | SAMPLE_4.
207//
208// Currently, only PCM type I encoding/decoding is supported!
209//
210// If the coding feature is to be used, support FIFOs need to be configured. Their sizes and numbers are defined below.
211
212// Encoding/decoding is done in software and thus time consuming. If you can encode/decode your stream more efficiently do not use the
213// support FIFOs but write/read directly into/from the EP_X_SW_BUFFER_FIFOs using
214// - tud_audio_n_write() or
215// - tud_audio_n_read().
216// To write/read to/from the support FIFOs use
217// - tud_audio_n_write_support_ff() or
218// - tud_audio_n_read_support_ff().
219//
220// The encoding/decoding format type done is defined below.
221//
222// The encoding/decoding starts when the private callback functions
223// - audio_tx_done_cb()
224// - audio_rx_done_cb()
225// are invoked. If support FIFOs are used, the corresponding encoding/decoding functions are called from there.
226// Once encoding/decoding is done the result is put directly into the EP_X_SW_BUFFER_FIFOs. You can use the public callback functions
227// - tud_audio_tx_done_pre_load_cb() or tud_audio_tx_done_post_load_cb()
228// - tud_audio_rx_done_pre_read_cb() or tud_audio_rx_done_post_read_cb()
229// if you want to get informed what happened.
230//
231// If you don't use the support FIFOs you may use the public callback functions
232// - tud_audio_tx_done_pre_load_cb() or tud_audio_tx_done_post_load_cb()
233// - tud_audio_rx_done_pre_read_cb() or tud_audio_rx_done_post_read_cb()
234// to write/read from/into the EP_X_SW_BUFFER_FIFOs at the right time.
235//
236// If you need a different encoding which is not support so far implement it in the
237// - audio_tx_done_cb()
238// - audio_rx_done_cb()
239// functions.
240
241// Enable encoding/decodings - for these to work, support FIFOs need to be setup in appropriate numbers and size
242// The actual coding parameters of active AS alternate interface is parsed from the descriptors
243
244// The item size of the FIFO is always fixed to one i.e. bytes! Furthermore, the actively used FIFO depth is reconfigured such that the depth is a multiple of the current sample size in order to avoid samples to get split up in case of a wrap in the FIFO ring buffer (depth = (max_depth / sampe_sz) * sampe_sz)!
245// This is important to remind in case you use DMAs! If the sample sizes changes, the DMA MUST BE RECONFIGURED just like the FIFOs for a different depth!!!
246
247// For PCM encoding/decoding
248
249#ifndef CFG_TUD_AUDIO_ENABLE_ENCODING
250#define CFG_TUD_AUDIO_ENABLE_ENCODING 0
251#endif
252
253#ifndef CFG_TUD_AUDIO_ENABLE_DECODING
254#define CFG_TUD_AUDIO_ENABLE_DECODING 0
255#endif
256
257// This enabling allows to save the current coding parameters e.g. # of bytes per sample etc. - TYPE_I includes common PCM encoding
258#ifndef CFG_TUD_AUDIO_ENABLE_TYPE_I_ENCODING
259#define CFG_TUD_AUDIO_ENABLE_TYPE_I_ENCODING 0
260#endif
261
262#ifndef CFG_TUD_AUDIO_ENABLE_TYPE_I_DECODING
263#define CFG_TUD_AUDIO_ENABLE_TYPE_I_DECODING 0
264#endif
265
266// Type I Coding parameters not given within UAC2 descriptors
267// It would be possible to allow for a more flexible setting and not fix this parameter as done below. However, this is most often not needed and kept for later if really necessary. The more flexible setting could be implemented within set_interface(), however, how the values are saved per alternate setting is to be determined!
268#if CFG_TUD_AUDIO_ENABLE_EP_IN && CFG_TUD_AUDIO_ENABLE_ENCODING && CFG_TUD_AUDIO_ENABLE_TYPE_I_ENCODING
269#ifndef CFG_TUD_AUDIO_FUNC_1_CHANNEL_PER_FIFO_TX
270#error You must tell the driver the number of channels per FIFO for the interleaved encoding! E.g. for an I2S interface having two channels, CHANNEL_PER_FIFO = 2 as the I2S stream having two channels is usually saved within one FIFO
271#endif
272#if CFG_TUD_AUDIO > 1
273#ifndef CFG_TUD_AUDIO_FUNC_2_CHANNEL_PER_FIFO_TX
274#error You must tell the driver the number of channels per FIFO for the interleaved encoding! E.g. for an I2S interface having two channels, CHANNEL_PER_FIFO = 2 as the I2S stream having two channels is usually saved within one FIFO
275#endif
276#endif
277#if CFG_TUD_AUDIO > 2
278#ifndef CFG_TUD_AUDIO_FUNC_3_CHANNEL_PER_FIFO_TX
279#error You must tell the driver the number of channels per FIFO for the interleaved encoding! E.g. for an I2S interface having two channels, CHANNEL_PER_FIFO = 2 as the I2S stream having two channels is usually saved within one FIFO
280#endif
281#endif
282#endif
283
284#if CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_DECODING && CFG_TUD_AUDIO_ENABLE_TYPE_I_DECODING
285#ifndef CFG_TUD_AUDIO_FUNC_1_CHANNEL_PER_FIFO_RX
286#error You must tell the driver the number of channels per FIFO for the interleaved encoding! E.g. for an I2S interface having two channels, CHANNEL_PER_FIFO = 2 as the I2S stream having two channels is usually saved within one FIFO
287#endif
288#if CFG_TUD_AUDIO > 1
289#ifndef CFG_TUD_AUDIO_FUNC_2_CHANNEL_PER_FIFO_RX
290#error You must tell the driver the number of channels per FIFO for the interleaved encoding! E.g. for an I2S interface having two channels, CHANNEL_PER_FIFO = 2 as the I2S stream having two channels is usually saved within one FIFO
291#endif
292#endif
293#if CFG_TUD_AUDIO > 2
294#ifndef CFG_TUD_AUDIO_FUNC_3_CHANNEL_PER_FIFO_RX
295#error You must tell the driver the number of channels per FIFO for the interleaved encoding! E.g. for an I2S interface having two channels, CHANNEL_PER_FIFO = 2 as the I2S stream having two channels is usually saved within one FIFO
296#endif
297#endif
298#endif
299
300// Remaining types not support so far
301
302// Number of support FIFOs to set up - multiple channels can be handled by one FIFO - very common is two channels per FIFO stemming from one I2S interface
303#ifndef CFG_TUD_AUDIO_FUNC_1_N_TX_SUPP_SW_FIFO
304#define CFG_TUD_AUDIO_FUNC_1_N_TX_SUPP_SW_FIFO 0
305#endif
306#ifndef CFG_TUD_AUDIO_FUNC_2_N_TX_SUPP_SW_FIFO
307#define CFG_TUD_AUDIO_FUNC_2_N_TX_SUPP_SW_FIFO 0
308#endif
309#ifndef CFG_TUD_AUDIO_FUNC_3_N_TX_SUPP_SW_FIFO
310#define CFG_TUD_AUDIO_FUNC_3_N_TX_SUPP_SW_FIFO 0
311#endif
312
313#ifndef CFG_TUD_AUDIO_FUNC_1_N_RX_SUPP_SW_FIFO
314#define CFG_TUD_AUDIO_FUNC_1_N_RX_SUPP_SW_FIFO 0
315#endif
316#ifndef CFG_TUD_AUDIO_FUNC_2_N_RX_SUPP_SW_FIFO
317#define CFG_TUD_AUDIO_FUNC_2_N_RX_SUPP_SW_FIFO 0
318#endif
319#ifndef CFG_TUD_AUDIO_FUNC_3_N_RX_SUPP_SW_FIFO
320#define CFG_TUD_AUDIO_FUNC_3_N_RX_SUPP_SW_FIFO 0
321#endif
322
323// Size of support FIFOs IN BYTES - if size > 0 there are as many FIFOs set up as CFG_TUD_AUDIO_FUNC_X_N_TX_SUPP_SW_FIFO and CFG_TUD_AUDIO_FUNC_X_N_RX_SUPP_SW_FIFO
324#ifndef CFG_TUD_AUDIO_FUNC_1_TX_SUPP_SW_FIFO_SZ
325#define CFG_TUD_AUDIO_FUNC_1_TX_SUPP_SW_FIFO_SZ 0 // FIFO size - minimum size: ceil(f_s/1000) * max(# of TX channels) / (# of TX support FIFOs) * max(# of bytes per sample)
326#endif
327#ifndef CFG_TUD_AUDIO_FUNC_2_TX_SUPP_SW_FIFO_SZ
328#define CFG_TUD_AUDIO_FUNC_2_TX_SUPP_SW_FIFO_SZ 0
329#endif
330#ifndef CFG_TUD_AUDIO_FUNC_3_TX_SUPP_SW_FIFO_SZ
331#define CFG_TUD_AUDIO_FUNC_3_TX_SUPP_SW_FIFO_SZ 0
332#endif
333
334#ifndef CFG_TUD_AUDIO_FUNC_1_RX_SUPP_SW_FIFO_SZ
335#define CFG_TUD_AUDIO_FUNC_1_RX_SUPP_SW_FIFO_SZ 0 // FIFO size - minimum size: ceil(f_s/1000) * max(# of RX channels) / (# of RX support FIFOs) * max(# of bytes per sample)
336#endif
337#ifndef CFG_TUD_AUDIO_FUNC_2_RX_SUPP_SW_FIFO_SZ
338#define CFG_TUD_AUDIO_FUNC_2_RX_SUPP_SW_FIFO_SZ 0
339#endif
340#ifndef CFG_TUD_AUDIO_FUNC_3_RX_SUPP_SW_FIFO_SZ
341#define CFG_TUD_AUDIO_FUNC_3_RX_SUPP_SW_FIFO_SZ 0
342#endif
343
344//static_assert(sizeof(tud_audio_desc_lengths) != CFG_TUD_AUDIO, "Supply audio function descriptor pack length!");
345
346// Supported types of this driver:
347// AUDIO_DATA_FORMAT_TYPE_I_PCM - Required definitions: CFG_TUD_AUDIO_N_CHANNELS and CFG_TUD_AUDIO_BYTES_PER_CHANNEL
348
349#ifdef __cplusplus
350extern "C" {
351#endif
352
358//--------------------------------------------------------------------+
359// Application API (Multiple Interfaces)
360// CFG_TUD_AUDIO > 1
361//--------------------------------------------------------------------+
362bool tud_audio_n_mounted (uint8_t func_id);
363
364#if CFG_TUD_AUDIO_ENABLE_EP_OUT && !CFG_TUD_AUDIO_ENABLE_DECODING
365uint16_t tud_audio_n_available (uint8_t func_id);
366uint16_t tud_audio_n_read (uint8_t func_id, void* buffer, uint16_t bufsize);
367bool tud_audio_n_clear_ep_out_ff (uint8_t func_id); // Delete all content in the EP OUT FIFO
368tu_fifo_t* tud_audio_n_get_ep_out_ff (uint8_t func_id);
369#endif
370
371#if CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_DECODING
372bool tud_audio_n_clear_rx_support_ff (uint8_t func_id, uint8_t ff_idx); // Delete all content in the support RX FIFOs
373uint16_t tud_audio_n_available_support_ff (uint8_t func_id, uint8_t ff_idx);
374uint16_t tud_audio_n_read_support_ff (uint8_t func_id, uint8_t ff_idx, void* buffer, uint16_t bufsize);
375tu_fifo_t* tud_audio_n_get_rx_support_ff (uint8_t func_id, uint8_t ff_idx);
376#endif
377
378#if CFG_TUD_AUDIO_ENABLE_EP_IN && !CFG_TUD_AUDIO_ENABLE_ENCODING
379uint16_t tud_audio_n_write (uint8_t func_id, const void * data, uint16_t len);
380bool tud_audio_n_clear_ep_in_ff (uint8_t func_id); // Delete all content in the EP IN FIFO
381tu_fifo_t* tud_audio_n_get_ep_in_ff (uint8_t func_id);
382#endif
383
384#if CFG_TUD_AUDIO_ENABLE_EP_IN && CFG_TUD_AUDIO_ENABLE_ENCODING
385uint16_t tud_audio_n_flush_tx_support_ff (uint8_t func_id); // Force all content in the support TX FIFOs to be written into EP SW FIFO
386bool tud_audio_n_clear_tx_support_ff (uint8_t func_id, uint8_t ff_idx);
387uint16_t tud_audio_n_write_support_ff (uint8_t func_id, uint8_t ff_idx, const void * data, uint16_t len);
388tu_fifo_t* tud_audio_n_get_tx_support_ff (uint8_t func_id, uint8_t ff_idx);
389#endif
390
391#if CFG_TUD_AUDIO_INT_CTR_EPSIZE_IN
392uint16_t tud_audio_int_ctr_n_write (uint8_t func_id, uint8_t const* buffer, uint16_t len);
393#endif
394
395//--------------------------------------------------------------------+
396// Application API (Interface0)
397//--------------------------------------------------------------------+
398
399static inline bool tud_audio_mounted (void);
400
401// RX API
402
403#if CFG_TUD_AUDIO_ENABLE_EP_OUT && !CFG_TUD_AUDIO_ENABLE_DECODING
404static inline uint16_t tud_audio_available (void);
405static inline bool tud_audio_clear_ep_out_ff (void); // Delete all content in the EP OUT FIFO
406static inline uint16_t tud_audio_read (void* buffer, uint16_t bufsize);
407static inline tu_fifo_t* tud_audio_get_ep_out_ff (void);
408#endif
409
410#if CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_DECODING
411static inline bool tud_audio_clear_rx_support_ff (uint8_t ff_idx);
412static inline uint16_t tud_audio_available_support_ff (uint8_t ff_idx);
413static inline uint16_t tud_audio_read_support_ff (uint8_t ff_idx, void* buffer, uint16_t bufsize);
414static inline tu_fifo_t* tud_audio_get_rx_support_ff (uint8_t ff_idx);
415#endif
416
417// TX API
418
419#if CFG_TUD_AUDIO_ENABLE_EP_IN && !CFG_TUD_AUDIO_ENABLE_ENCODING
420static inline uint16_t tud_audio_write (const void * data, uint16_t len);
421static inline bool tud_audio_clear_ep_in_ff (void);
422static inline tu_fifo_t* tud_audio_get_ep_in_ff (void);
423#endif
424
425#if CFG_TUD_AUDIO_ENABLE_EP_IN && CFG_TUD_AUDIO_ENABLE_ENCODING
426static inline uint16_t tud_audio_flush_tx_support_ff (void);
427static inline uint16_t tud_audio_clear_tx_support_ff (uint8_t ff_idx);
428static inline uint16_t tud_audio_write_support_ff (uint8_t ff_idx, const void * data, uint16_t len);
429static inline tu_fifo_t* tud_audio_get_tx_support_ff (uint8_t ff_idx);
430#endif
431
432// INT CTR API
433
434#if CFG_TUD_AUDIO_INT_CTR_EPSIZE_IN
435static inline uint16_t tud_audio_int_ctr_write (uint8_t const* buffer, uint16_t len);
436#endif
437
438// Buffer control EP data and schedule a transmit
439// This function is intended to be used if you do not have a persistent buffer or memory location available (e.g. non-local variables) and need to answer onto a
440// get request. This function buffers your answer request frame into the control buffer of the corresponding audio driver and schedules a transmit for sending it.
441// Since transmission is triggered via interrupts, a persistent memory location is required onto which the buffer pointer in pointing. If you already have such
442// available you may directly use 'tud_control_xfer(...)'. In this case data does not need to be copied into an additional buffer and you save some time.
443// If the request's wLength is zero, a status packet is sent instead.
444bool tud_audio_buffer_and_schedule_control_xfer(uint8_t rhport, tusb_control_request_t const * p_request, void* data, uint16_t len);
445
446//--------------------------------------------------------------------+
447// Application Callback API (weak is optional)
448//--------------------------------------------------------------------+
449
450#if CFG_TUD_AUDIO_ENABLE_EP_IN
451TU_ATTR_WEAK bool tud_audio_tx_done_pre_load_cb(uint8_t rhport, uint8_t func_id, uint8_t ep_in, uint8_t cur_alt_setting);
452TU_ATTR_WEAK bool tud_audio_tx_done_post_load_cb(uint8_t rhport, uint16_t n_bytes_copied, uint8_t func_id, uint8_t ep_in, uint8_t cur_alt_setting);
453#endif
454
455#if CFG_TUD_AUDIO_ENABLE_EP_OUT
456TU_ATTR_WEAK bool tud_audio_rx_done_pre_read_cb(uint8_t rhport, uint16_t n_bytes_received, uint8_t func_id, uint8_t ep_out, uint8_t cur_alt_setting);
457TU_ATTR_WEAK bool tud_audio_rx_done_post_read_cb(uint8_t rhport, uint16_t n_bytes_received, uint8_t func_id, uint8_t ep_out, uint8_t cur_alt_setting);
458#endif
459
460#if CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP
461TU_ATTR_WEAK void tud_audio_fb_done_cb(uint8_t func_id);
462
463
464// determined by the user itself and set by use of tud_audio_n_fb_set(). The feedback value may be determined e.g. from some fill status of some FIFO buffer. Advantage: No ISR interrupt is enabled, hence the CPU need not to handle an ISR every 1ms or 125us and thus less CPU load, disadvantage: typically a larger FIFO is needed to compensate for jitter (e.g. 8 frames), i.e. a larger delay is introduced.
465
466// Feedback value is calculated within the audio driver by use of SOF interrupt. The driver needs information about the master clock f_m from which the audio sample frequency f_s is derived, f_s itself, and the cycle count of f_m at time of the SOF interrupt (e.g. by use of a hardware counter) - see tud_audio_set_fb_params(). Advantage: Reduced jitter in the feedback value computation, hence, the receive FIFO can be smaller (e.g. 2 frames) and thus a smaller delay is possible, disadvantage: higher CPU load due to SOF ISR handling every frame i.e. 1ms or 125us. This option is a great starting point to try the SOF ISR option but depending on your hardware setup (performance of the CPU) it might not work. If so, figure out why and use the next option. (The most critical point is the reading of the cycle counter value of f_m. It is read from within the SOF ISR - see: audiod_sof() -, hence, the ISR must has a high priority such that no software dependent "random" delay i.e. jitter is introduced).
467
468// Feedback value is determined by the user by use of SOF interrupt. The user may use tud_audio_sof_isr() which is called every SOF (of course only invoked when an alternate interface other than zero was set). The number of frames used to determine the feedback value for the currently active alternate setting can be get by tud_audio_get_fb_n_frames(). The feedback value must be set by use of tud_audio_n_fb_set().
469
470// This function is used to provide data rate feedback from an asynchronous sink. Feedback value will be sent at FB endpoint interval till it's changed.
471//
472// The feedback format is specified to be 16.16 for HS and 10.14 for FS devices (see Universal Serial Bus Specification Revision 2.0 5.12.4.2). By default,
473// the choice of format is left to the caller and feedback argument is sent as-is. If CFG_TUD_AUDIO_ENABLE_FEEDBACK_FORMAT_CORRECTION is set, then tinyusb
474// expects 16.16 format and handles the conversion to 10.14 on FS.
475//
476// Note that due to a bug in its USB Audio 2.0 driver, Windows currently requires 16.16 format for _all_ USB 2.0 devices. On Linux and macOS it seems the
477// driver can work with either format. So a good compromise is to keep format correction disabled and stick to 16.16 format.
478
479// Feedback value can be determined from within the SOF ISR of the audio driver. This should reduce jitter. If the feature is used, the user can not set the feedback value.
480
481// Determine feedback value - The feedback method is described in 5.12.4.2 of the USB 2.0 spec
482// Boiled down, the feedback value Ff = n_samples / (micro)frame.
483// Since an accuracy of less than 1 Sample / second is desired, at least n_frames = ceil(2^K * f_s / f_m) frames need to be measured, where K = 10 for full speed and K = 13 for high speed, f_s is the sampling frequency e.g. 48 kHz and f_m is the cpu clock frequency e.g. 100 MHz (or any other master clock whose clock count is available and locked to f_s)
484// The update interval in the (4.10.2.1) Feedback Endpoint Descriptor must be less or equal to 2^(K - P), where P = min( ceil(log2(f_m / f_s)), K)
485// feedback = n_cycles / n_frames * f_s / f_m in 16.16 format, where n_cycles are the number of main clock cycles within fb_n_frames
486
487bool tud_audio_n_fb_set(uint8_t func_id, uint32_t feedback);
488static inline bool tud_audio_fb_set(uint32_t feedback);
489
490// Update feedback value with passed cycles since last time this update function is called.
491// Typically called within tud_audio_sof_isr(). Required tud_audio_feedback_params_cb() is implemented
492// This function will also call tud_audio_feedback_set()
493// return feedback value in 16.16 for reference (0 for error)
494uint32_t tud_audio_feedback_update(uint8_t func_id, uint32_t cycles);
495
496enum {
497 AUDIO_FEEDBACK_METHOD_DISABLED,
498 AUDIO_FEEDBACK_METHOD_FREQUENCY_FIXED,
499 AUDIO_FEEDBACK_METHOD_FREQUENCY_FLOAT,
500 AUDIO_FEEDBACK_METHOD_FREQUENCY_POWER_OF_2,
501
502 // impelemnt later
503 // AUDIO_FEEDBACK_METHOD_FIFO_COUNT
504};
505
506typedef struct {
507 uint8_t method;
508 uint32_t sample_freq; // sample frequency in Hz
509
510 union {
511 struct {
512 uint32_t mclk_freq; // Main clock frequency in Hz i.e. master clock to which sample clock is based on
513 }frequency;
514
515#if 0 // implement later
516 struct {
517 uint32_t threshold_bytes; // minimum number of bytes received to be considered as filled/ready
518 }fifo_count;
519#endif
520 };
521}audio_feedback_params_t;
522
523// Invoked when needed to set feedback parameters
524TU_ATTR_WEAK void tud_audio_feedback_params_cb(uint8_t func_id, uint8_t alt_itf, audio_feedback_params_t* feedback_param);
525
526// Callback in ISR context, invoked periodically according to feedback endpoint bInterval.
527// Could be used to compute and update feedback value, should be placed in RAM if possible
528// frame_number : current SOF count
529// interval_shift: number of bit shift i.e log2(interval) from Feedback endpoint descriptor
530TU_ATTR_WEAK TU_ATTR_FAST_FUNC void tud_audio_feedback_interval_isr(uint8_t func_id, uint32_t frame_number, uint8_t interval_shift);
531
532#endif // CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP
533
534#if CFG_TUD_AUDIO_INT_CTR_EPSIZE_IN
535TU_ATTR_WEAK bool tud_audio_int_ctr_done_cb(uint8_t rhport, uint16_t n_bytes_copied);
536#endif
537
538// Invoked when audio set interface request received
539TU_ATTR_WEAK bool tud_audio_set_itf_cb(uint8_t rhport, tusb_control_request_t const * p_request);
540
541// Invoked when audio set interface request received which closes an EP
542TU_ATTR_WEAK bool tud_audio_set_itf_close_EP_cb(uint8_t rhport, tusb_control_request_t const * p_request);
543
544// Invoked when audio class specific set request received for an EP
545TU_ATTR_WEAK bool tud_audio_set_req_ep_cb(uint8_t rhport, tusb_control_request_t const * p_request, uint8_t *pBuff);
546
547// Invoked when audio class specific set request received for an interface
548TU_ATTR_WEAK bool tud_audio_set_req_itf_cb(uint8_t rhport, tusb_control_request_t const * p_request, uint8_t *pBuff);
549
550// Invoked when audio class specific set request received for an entity
551TU_ATTR_WEAK bool tud_audio_set_req_entity_cb(uint8_t rhport, tusb_control_request_t const * p_request, uint8_t *pBuff);
552
553// Invoked when audio class specific get request received for an EP
554TU_ATTR_WEAK bool tud_audio_get_req_ep_cb(uint8_t rhport, tusb_control_request_t const * p_request);
555
556// Invoked when audio class specific get request received for an interface
557TU_ATTR_WEAK bool tud_audio_get_req_itf_cb(uint8_t rhport, tusb_control_request_t const * p_request);
558
559// Invoked when audio class specific get request received for an entity
560TU_ATTR_WEAK bool tud_audio_get_req_entity_cb(uint8_t rhport, tusb_control_request_t const * p_request);
561
562//--------------------------------------------------------------------+
563// Inline Functions
564//--------------------------------------------------------------------+
565
566static inline bool tud_audio_mounted(void)
567{
568 return tud_audio_n_mounted(0);
569}
570
571// RX API
572
573#if CFG_TUD_AUDIO_ENABLE_EP_OUT && !CFG_TUD_AUDIO_ENABLE_DECODING
574
575static inline uint16_t tud_audio_available(void)
576{
577 return tud_audio_n_available(0);
578}
579
580static inline uint16_t tud_audio_read(void* buffer, uint16_t bufsize)
581{
582 return tud_audio_n_read(0, buffer, bufsize);
583}
584
585static inline bool tud_audio_clear_ep_out_ff(void)
586{
587 return tud_audio_n_clear_ep_out_ff(0);
588}
589
590static inline tu_fifo_t* tud_audio_get_ep_out_ff(void)
591{
592 return tud_audio_n_get_ep_out_ff(0);
593}
594
595#endif
596
597#if CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_DECODING
598
599static inline bool tud_audio_clear_rx_support_ff(uint8_t ff_idx)
600{
601 return tud_audio_n_clear_rx_support_ff(0, ff_idx);
602}
603
604static inline uint16_t tud_audio_available_support_ff(uint8_t ff_idx)
605{
606 return tud_audio_n_available_support_ff(0, ff_idx);
607}
608
609static inline uint16_t tud_audio_read_support_ff(uint8_t ff_idx, void* buffer, uint16_t bufsize)
610{
611 return tud_audio_n_read_support_ff(0, ff_idx, buffer, bufsize);
612}
613
614static inline tu_fifo_t* tud_audio_get_rx_support_ff(uint8_t ff_idx)
615{
616 return tud_audio_n_get_rx_support_ff(0, ff_idx);
617}
618
619#endif
620
621// TX API
622
623#if CFG_TUD_AUDIO_ENABLE_EP_IN && !CFG_TUD_AUDIO_ENABLE_ENCODING
624
625static inline uint16_t tud_audio_write(const void * data, uint16_t len)
626{
627 return tud_audio_n_write(0, data, len);
628}
629
630static inline bool tud_audio_clear_ep_in_ff(void)
631{
632 return tud_audio_n_clear_ep_in_ff(0);
633}
634
635static inline tu_fifo_t* tud_audio_get_ep_in_ff(void)
636{
637 return tud_audio_n_get_ep_in_ff(0);
638}
639
640#endif
641
642#if CFG_TUD_AUDIO_ENABLE_EP_IN && CFG_TUD_AUDIO_ENABLE_ENCODING
643
644static inline uint16_t tud_audio_flush_tx_support_ff(void)
645{
646 return tud_audio_n_flush_tx_support_ff(0);
647}
648
649static inline uint16_t tud_audio_clear_tx_support_ff(uint8_t ff_idx)
650{
651 return tud_audio_n_clear_tx_support_ff(0, ff_idx);
652}
653
654static inline uint16_t tud_audio_write_support_ff(uint8_t ff_idx, const void * data, uint16_t len)
655{
656 return tud_audio_n_write_support_ff(0, ff_idx, data, len);
657}
658
659static inline tu_fifo_t* tud_audio_get_tx_support_ff(uint8_t ff_idx)
660{
661 return tud_audio_n_get_tx_support_ff(0, ff_idx);
662}
663
664#endif
665
666#if CFG_TUD_AUDIO_INT_CTR_EPSIZE_IN
667static inline uint16_t tud_audio_int_ctr_write(uint8_t const* buffer, uint16_t len)
668{
669 return tud_audio_int_ctr_n_write(0, buffer, len);
670}
671#endif
672
673#if CFG_TUD_AUDIO_ENABLE_EP_OUT && CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP
674
675static inline bool tud_audio_fb_set(uint32_t feedback)
676{
677 return tud_audio_n_fb_set(0, feedback);
678}
679
680#endif
681
682//--------------------------------------------------------------------+
683// Internal Class Driver API
684//--------------------------------------------------------------------+
685void audiod_init (void);
686void audiod_reset (uint8_t rhport);
687uint16_t audiod_open (uint8_t rhport, tusb_desc_interface_t const * itf_desc, uint16_t max_len);
688bool audiod_control_xfer_cb(uint8_t rhport, uint8_t stage, tusb_control_request_t const * request);
689bool audiod_xfer_cb (uint8_t rhport, uint8_t edpt_addr, xfer_result_t result, uint32_t xferred_bytes);
690void audiod_sof_isr (uint8_t rhport, uint32_t frame_count);
691
692#ifdef __cplusplus
693}
694#endif
695
696#endif /* _TUSB_AUDIO_DEVICE_H_ */
697
TU_ATTR_PACKED
AUDIO Channel Cluster Descriptor (4.1)
Definition audio.h:647
tu_fifo_t
Definition tusb_fifo.h:108