Audio DMA Driver

The Audio DMA driver provides a set of data buffer based transfer functions, both of writing or reads data to/from the audio peripheral. Each buffer should be assigned with a handler. In the Audio DMA driver, a callback function can be registered in the driver by the application and triggered when buffer transfer is done to let the application know the transfer result. The callback function has a handler parameter to let the application know which buffer was processed. The driver has an internal buffer queue mechanism, the queue size can be configurable in drivers configurations. The driver also needs to know the DMA channel number for each write and read.

Summary of the API's Functional Features

The API provides functions to:

Initialize and deinitialize the driver and associated hardware
Hookup callback handlers on data buffer transfer done
Enable or disable Audio hardware
Add buffer to write/read data from hardware
Flush(discard) data buffer for write/read which not transferred yet
Return the number of bytes has been processed in the buffer queue

Summary of Configuration Options

Below is a list of the main audio parameters that can be configured in START. Many of these parameters are used by the audio_dma_init function when initializing the driver and underlying hardware.

Select Clock for audio hardware to generate peripheral clock and audio clock.
Select Pin for audio hardware.
Configure Audio peripherals, such like data format, baud rate, etc.
Select DMA channel for data to write/read operation.
Select queue size for internal buffer queue mechanism.

Driver Implementation Description

After the Audio hardware initialization, the application can register the callback function for transfer done by audio_dma_register_callback, and invoke audio_dma_add_buffer to write/read data from audio hardware.

Example of Usage

The following shows a simple example of using the Audio DMA driver. The Audio must have been initialized by audio_dma_init. This initialization will configure the operation of the Audio Peripheral, such as the clock, input pins, baud rate, format, etc.

The example registers a callback function for data transfer done and enables Audio hardware, and then finally starts a buffer transfer to the hardware.

          audio_buffer_handler_t tx_buffer_handler = 0;
          uint8_t data[1024];
          uint8_t tx_result = 0;
          void audio_buffer_event_handler(enum audio_buffer_event event, audio_buffer_handler_t handler)
          {
              if (tx_buffer_handler == 0) {
                  if (event == AUDIO_BUFFER_EVENT_COMPLETE) {
                      tx_result = 1;
                  } else {
                      tx_result = 2;
                  }
              }
              
          }
          /**
           * Example of using AUDIO_0 to write data 
           */
          void audio_example(void)
          {
              uint32_t len;
              audio_dma_register_callback(&AUDIO_0, audio_buffer_event_handler);
              audio_dma_enable(&AUDIO_0);
              audio_dma_add_buffer(&AUDIO_0, AUDIO_WRITE, data, 1024);
              /* Wait for buffer send out */
              while (tx_result == 0) {
              }
              /**
                * Error handling here.
                * We can find out how many bytes were processed in this buffer
                * before the error occurred.
                */
              if (tx_result == 2) {
                  len = audio_dma_get_buffer_size(&AUDIO_0, AUDIO_WRITE);
              }
          }

Dependencies

The AUDIO peripheral and it's related I/O lines and clocks
The DMA peripheral and its configuration must be aligned with AUDIO peripheral