Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel3
minLevel2
indent20px

...

A playback stream carries audio data over an isochronous OUT endpoint. There is a one-to-one relation between an isochronous OUT endpoint, an AudioStreaming interface and a Terminal. 101482827 presents the audio data flow implemented inside the Audio Processing module. The playback path relies on a ring buffer queue to synchronize the playback task, the core task and the codec ISR.

...

Panel
bgColor#f0f0f0

(1) The host activates the AudioStreaming interface #X by selecting the operational interface (request SET_INTERFACE sent for alternate setting 1). The host then sets the sampling frequency for a certain isochronous IN endpoint by sending SET_CUR request. The function USBD_Audio_DrvAS_SamplingFreqManage  (not indicated in the figure) is called  from the core task's context . This function is implemented by the audio peripheral driver and will set an ADC (Analog-to-Digital Converter) clock in the codec.

(2) When processing the SET_CUR(sampling frequency) request, the audio class will also start the record stream on the codec side by calling StreamStart() . In this function, a DMA transfer will be prepared to get the first record buffer from the codec. The initial receive buffer will be obtained by calling USBD_Audio_RecordBufGet() . This step is not entirely represented in the figure. The audio class ensures that the record stream is started on the codec side after setting the sampling frequency as a codec needs the correct clock settings before getting record data.

Tip
titleDMA in Audio Peripheral Driver

The use of DMA transfers is assumed to communicate with the audio codec. It allows to offload the CPU and to optimize performances.

(3) Once the first DMA transfer has completed, the audio peripheral driver will obtain the next receive buffer from the ring buffer queue by calling USBD_Audio_RecordBufGet() . This This function provides also to the audio peripheral driver the number of bytes to get from the codec.

(4) The buffer will be filled with audio samples given by one or more ADCs (one ADC per logical channel). The buffer will contain 1 ms worth of audio samples. This 1 ms of audio samples should be encoded, either directly by the codec (hardware) or by the audio peripheral driver (software). Most of the time, the codec will provide the chunk of audio stream already encoded. The driver signals the end of an audio transfer to the record task by calling the function USBD_Audio_RecordRxCmpl() . The signal represents an AudioStreaming interface handle.

(5) The record task wakes up and retrieves the ready buffer from the audio peripheral driver by calling the audio peripheral driver function StreamRecordRx() . The buffer is stored in the ring buffer queue.

(6) To prime the audio stream, the record task waits for a certain number of buffers to be ready. The pre-bufferring threshold is always equal to (MaxBufNbr / 2). The field  MaxBufNbr is part of the structure USBD_AUDIO_STREAM_CFG . Once the pre-buffering is done, the record task submits the initial isochronous IN transfer to the USB device driver via USBD_IsocTxAsync() . During the stream communication, the record task does not submit other isochronous transfers. Other USB transfers submission is done by the core task.

There is a special situation where the record task can submit a new transfer. When the stream communication loop is broken, that is there are no more ongoing isochronous transfers in the USB device driver, the record task restarts the stream with a new USB transfer.

(7) The USB device driver will send isochronous audio data to the host during a specific frame.

(8) Upon completion of the isochronous IN transfer, the core task will call the callback USBD_Audio_RecordIsocCmpl() provided by the Audio Processing as an argument of USBD_IsocTxAsync() . This callback will free the buffer by returning it in the ring buffer queue. Before the buffer return int the ring buffer queue, a stream correction may happen for the next record buffer to fill by the codec. The record stream correction is explained in section  Record Stream Correction.  

Info
titleError Handling

If a transfer has completed with an error, the associated buffer is freed by USBD_Audio_RecordIsocCmpl().

(9) The core task submits all the ready buffers it can to the USB device driver by calling USBD_IsocTxAsync()  several times. The core task is thus responsible to maintain alive the stream communication by repeating the steps 7 and 8.

Info
titleError Handling

If the submission with  USBD_IsocTxAsync()  fails by returning an error code, the buffer is freed back to the ring buffer queue ..

(10) Once the audio stream is initiated, the steps 3 to 8 will repeat over and over again until the host stops recording by selecting the default AudioStreaming Interface (request SET_INTERFACE sent for alternate setting 0). At this time, the Audio Processing will stop the streaming on the codec side by calling the audio peripheral driver function StreamRecordStop() . Basically, any record DMA transfer will be aborted. All empty buffers being processed and all ready buffers not yet retrieved by the record task are implicitly freed by the ring buffer queue reset. On the USB side, all the record buffers unconsumed will be freed automatically by the core by calling USBD_Audio_IsocRecordCmpl() for each aborted isochronous transfers.

Info

Refer to page Audio Peripheral Driver Guide for more details about the audio peripheral driver processing.


...

Panel
borderWidth0
titleFigure - Playback Ring Buffers Queue Monitoring


Figure - Adding a Sample in Case of Underrun illustrates the algorithm to add an audio sample in case of underrun situation. 

...

Warning

This stream correction is convenient for low-cost audio design. It will give good results as long as the incoming USB audio sampling frequency is very close to the DAC input clock frequency. However, if the difference between the two frequencies is important, this will add audio distortion.

Figure - Removing a Sample in Case of Overrun illustrates the algorithm to remove an audio sample in case of overrun situation. 

...

The playback stream correction offers the possibility to apply your own correction algorithm. If an underrun or overrun situation is detected, an application callback is called. Listing - Example of Playback Correction Callback Provided by the Application shows an example of playback correction callback prototype and definition provided by the application. 

...

Panel
bgColor#f0f0f0

(1) Prototype of your playback correction callback.

(2) Upon configuration of an AudioStreaming interface with the function USBD_Audio_AS_IF_Cfg , the callback function name is passed to the function. You have the possibility to define a different correction callback for each playback AudioStreaming interface composing your audio topology.

(3) Definition of your playback correction callback. Once the playback is open by the host and the built-in playback correction is enabled (USBD_AUDIO_CFG_PLAYBACK_CORR_EN set to DEF_ENABLED), if an overrun or underrun situation is detected by the Audio Processing module, your callback will be called. You will have access to the structure USBD_AUDIO_AS_ALT_CFG associated to this playback stream through the pointer p_as_alt_cfg. Among the fields, you may be interested in:

  • TerminalID: ID of terminal associated to the playback stream.
  • NbrCh: Number of channels supported by the stream.
  • SubframeSize: Number of bytes occupied by one audio sample.
  • BitRes: Effectively used bits in an audio sample.

Beside the AudioStreaming alternate setting configuration structure, you will know the situation type (underrun or overrun via underrun_flag), the current buffer length (buf_len_cur) and the total buffer length ( buf_len_total ). Then you can apply your own correction algorithm to the buffer referenced by p_buf. If some samples are removed or added to the buffer, you will have to return to the Audio Processing module the adjusted buffer length. Note that you can add or remove only one sample at a time. You can also specify an error code if something went wrong while applying your correction.

...

Consequently, if the lower limit is reached, you have an overrun situation, that is the USB side consumes a little bit faster than the the codec can produce. Conversely, the upper limit corresponds to an underrun situation, that is the USB side does not consume fast enough the audio samples produced by the codec. As opposed to the playback stream correction, no software algorithm is needed to add or remove an audio sample. The audio class will adjust the audio peripheral hardware by using the number of required record data bytes indicated by  USBD_Audio_RecordBufGet() . The correction is done implicitly by the audio peripheral hardware by directly getting the right number of audio samples (-1 sample frame or +1 sample frame) to accommodate the overrun or underrun situation.

The frequency at which the record stream correction is evaluated is configurable via the field CorrPeriodMs of the structure USBD_AUDIO_STREAM_CFG .

Playback Feedback Correction

...

The feedback value update to the host is evaluated every refresh period. The refresh period is configurable via the field CorrPeriodMs of the structure  USBD_AUDIO_STREAM_CFG . When the refresh period is reached, if there is a correction to apply, the feedback value update is sent to the host by calling the function USBD_IsocTxAsync() . If there is no correction necessary, the audio class does not prepare an isochronous IN transfer. Thus when the host sends an IN token, a zero-length packet is sent by the device. The host interprets this zero-length packet as "continue to apply the previous valid feedback value". The feedback value is sent in 10.14 format.

...