/*
* SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "driver/dac_types.h"
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
#if SOC_DAC_SUPPORTED
/**
* @brief DAC channel mask
*
*/
typedef enum {
DAC_CHANNEL_MASK_CH0 = BIT(0), /*!< DAC channel 0 is GPIO25(ESP32) / GPIO17(ESP32S2) */
DAC_CHANNEL_MASK_CH1 = BIT(1), /*!< DAC channel 1 is GPIO26(ESP32) / GPIO18(ESP32S2) */
DAC_CHANNEL_MASK_ALL = BIT(0) | BIT(1), /*!< Both DAC channel 0 and channel 1 */
} dac_channel_mask_t;
typedef struct dac_continuous_s *dac_continuous_handle_t; /*!< DAC continuous channel handle */
/**
* @brief DAC continuous channels' configurations
*
*/
typedef struct {
dac_channel_mask_t chan_mask; /*!< DAC channels' mask for selecting which channels are used */
uint32_t desc_num; /*!< The number of DMA descriptor, at least 2 descriptors are required
* The number of descriptors is directly proportional to the max data buffer size while converting in cyclic output
* but only need to ensure it is greater than '1' in acyclic output
* Typically, suggest to set the number bigger than 5, in case the DMA stopped while sending a short buffer
*/
size_t buf_size; /*!< The DMA buffer size, should be within 32~4092 bytes. Each DMA buffer will be attached to a DMA descriptor,
* i.e. the number of DMA buffer will be equal to the DMA descriptor number
* The DMA buffer size is not allowed to be greater than 4092 bytes
* The total DMA buffer size equal to `desc_num * buf_size`
* Typically, suggest to set the size to the multiple of 4
*/
uint32_t freq_hz; /*!< The frequency of DAC conversion in continuous mode, unit: Hz
* The supported range is related to the target and the clock source.
* For the clock `DAC_DIGI_CLK_SRC_DEFAULT`: the range is 19.6 KHz to several MHz on ESP32
* and 77 Hz to several MHz on ESP32-S2.
* For the clock `DAC_DIGI_CLK_SRC_APLL`: the range is 648 Hz to several MHz on ESP32
* and 6 Hz to several MHz on ESP32-S2.
* Typically not suggest to set the frequency higher than 2 MHz, otherwise the severe distortion will appear
*/
int8_t offset; /*!< The offset of the DAC digital data. Range -128~127 */
dac_continuous_digi_clk_src_t clk_src; /*!< The clock source of digital controller, which can affect the range of supported frequency
* Currently `DAC_DIGI_CLK_SRC_DEFAULT` and `DAC_DIGI_CLK_SRC_APLL` are available
*/
dac_continuous_channel_mode_t chan_mode; /*!< The channel mode of continuous mode, only take effect when multiple channels enabled, depends converting the buffer alternately or simultaneously */
} dac_continuous_config_t;
/**
* @brief Event structure used in DAC event queue
*/
typedef struct {
void *buf; /*!< The pointer of DMA buffer that just finished sending */
size_t buf_size; /*!< The writable buffer size of the DMA buffer, equal to 'dac_continuous_config_t::buf_size' */
size_t write_bytes; /*!< The number of bytes that be written successfully */
} dac_event_data_t;
/**
* @brief DAC event callback
* @param[in] handle DAC channel handle, created from `dac_continuous_new_channels()`
* @param[in] event DAC event data
* @param[in] user_data User registered context, passed from `dac_continuous_register_event_callback()`
*
* @return Whether a high priority task has been waken up by this callback function
*/
typedef bool (*dac_isr_callback_t)(dac_continuous_handle_t handle, const dac_event_data_t *event, void *user_data);
/**
* @brief Group of DAC callbacks
* @note The callbacks are all running under ISR environment
* @note When CONFIG_DAC_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM.
* The variables used in the function should be in the SRAM as well.
*/
typedef struct {
dac_isr_callback_t on_convert_done; /**< Callback of data conversion done event
* An event data buffer previously loaded to the driver has been output and converted.
* The event data includes DMA buffer address and size that just finished converting.
*/
dac_isr_callback_t on_stop; /**< Callback of finished sending all the data.
* All loaded event data buffers are converted. Driver is pending for new data buffers to be loaded.
* The event data will be NULL in this callback.
*/
} dac_event_callbacks_t;
/**
* @brief Allocate new DAC channels in continuous mode
* @note The DAC channels can't be registered to continuous mode separately
*
* @param[in] cont_cfg Continuous mode configuration
* @param[out] ret_handle The returned continuous mode handle
* @return
* - ESP_ERR_INVALID_ARG The input parameter is invalid
* - ESP_ERR_INVALID_STATE The DAC channel has been registered already
* - ESP_ERR_NOT_FOUND Not found the available dma peripheral, might be occupied
* - ESP_ERR_NO_MEM No memory for the DAC continuous mode resources
* - ESP_OK Allocate the new DAC continuous mode success
*/
esp_err_t dac_continuous_new_channels(const dac_continuous_config_t *cont_cfg, dac_continuous_handle_t *ret_handle);
/**
* @brief Delete the DAC continuous handle
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @return
* - ESP_ERR_INVALID_ARG The input parameter is invalid
* - ESP_ERR_INVALID_STATE The channels have already been deregistered or not disabled
* - ESP_OK Delete the continuous channels success
*/
esp_err_t dac_continuous_del_channels(dac_continuous_handle_t handle);
/**
* @brief Enabled the DAC continuous mode
* @note Must enable the channels before
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @return
* - ESP_ERR_INVALID_ARG The input parameter is invalid
* - ESP_ERR_INVALID_STATE The channels have been enabled already
* - ESP_OK Enable the continuous output success
*/
esp_err_t dac_continuous_enable(dac_continuous_handle_t handle);
/**
* @brief Disable the DAC continuous mode
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @return
* - ESP_ERR_INVALID_ARG The input parameter is invalid
* - ESP_ERR_INVALID_STATE The channels have been enabled already
* - ESP_OK Disable the continuous output success
*/
esp_err_t dac_continuous_disable(dac_continuous_handle_t handle);
/**
* @brief Write DAC data continuously
* @note The data in buffer will only be converted one time,
* This function will be blocked until all data loaded or timeout
* then the DAC output will keep outputting the voltage of the last data in the buffer
* @note Specially, on ESP32, the data bit width of DAC continuous data is fixed to 16 bits while only the high 8 bits are available,
* The driver will help to expand the inputted buffer automatically by default,
* you can also align the data to 16 bits manually by clearing `CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` in menuconfig.
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @param[in] buf The digital data buffer to convert
* @param[in] buf_size The buffer size of digital data buffer
* @param[out] bytes_loaded The bytes that has been loaded into DMA buffer, can be NULL if don't need it
* @param[in] timeout_ms The timeout time in millisecond, set a minus value means will block forever
* @return
* - ESP_ERR_INVALID_ARG The input parameter is invalid
* - ESP_ERR_INVALID_STATE The DAC continuous mode has not been enabled yet
* - ESP_ERR_TIMEOUT Waiting for semaphore or message queue timeout
* - ESP_OK Success to output the acyclic DAC data
*/
esp_err_t dac_continuous_write(dac_continuous_handle_t handle, uint8_t *buf, size_t buf_size, size_t *bytes_loaded, int timeout_ms);
/**
* @brief Write DAC continuous data cyclically
* @note The data in buffer will be converted cyclically using DMA once this function is called,
* This function will return once the data loaded into DMA buffers.
* @note The buffer size of cyclically output is limited by the descriptor number and
* dma buffer size while initializing the continuous mode.
* Concretely, in order to load all the data into descriptors,
* the cyclic buffer size is not supposed to be greater than `desc_num * buf_size`
* @note Specially, on ESP32, the data bit width of DAC continuous data is fixed to 16 bits while only the high 8 bits are available,
* The driver will help to expand the inputted buffer automatically by default,
* you can also align the data to 16 bits manually by clearing `CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` in menuconfig.
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @param[in] buf The digital data buffer to convert
* @param[in] buf_size The buffer size of digital data buffer
* @param[out] bytes_loaded The bytes that has been loaded into DMA buffer, can be NULL if don't need it
* @return
* - ESP_ERR_INVALID_ARG The input parameter is invalid
* - ESP_ERR_INVALID_STATE The DAC continuous mode has not been enabled yet
* - ESP_OK Success to output the acyclic DAC data
*/
esp_err_t dac_continuous_write_cyclically(dac_continuous_handle_t handle, uint8_t *buf, size_t buf_size, size_t *bytes_loaded);
/**
* @brief Set event callbacks for DAC continuous mode
*
* @note User can deregister a previously registered callback by calling this function and setting the callback member in the `callbacks` structure to NULL.
* @note When CONFIG_DAC_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM.
* The variables used in this function, including the `user_data`, should be in the internal RAM as well.
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @param[in] callbacks Group of callback functions, input NULL to clear the former callbacks
* @param[in] user_data User data, which will be passed to callback functions directly
* @return
* - ESP_OK Set event callbacks successfully
* - ESP_ERR_INVALID_ARG Set event callbacks failed because of invalid argument
*/
esp_err_t dac_continuous_register_event_callback(dac_continuous_handle_t handle, const dac_event_callbacks_t *callbacks, void *user_data);
/**
* @brief Start the async writing
* @note When the asynchronous writing start, the DAC will keep outputting '0' until the data are loaded into the DMA buffer.
* To loaded the data into DMA buffer, 'on_convert_done' callback is required,
* which can be registered by 'dac_continuous_register_event_callback' before enabling
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @return
* - ESP_OK Start asynchronous writing successfully
* - ESP_ERR_INVALID_ARG The handle is NULL
* - ESP_ERR_INVALID_STATE The channel is not enabled or the 'on_convert_done' callback is not registered
*/
esp_err_t dac_continuous_start_async_writing(dac_continuous_handle_t handle);
/**
* @brief Stop the sync writing
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @return
* - ESP_OK Stop asynchronous writing successfully
* - ESP_ERR_INVALID_ARG The handle is NULL
* - ESP_ERR_INVALID_STATE Asynchronous writing has not started
*/
esp_err_t dac_continuous_stop_async_writing(dac_continuous_handle_t handle);
/**
* @brief Write DAC data asynchronously
* @note This function can be called when the asynchronous writing started, and it can be called in the callback directly
* but recommend to writing data in a task, referring to :example:`peripherals/dac/dac_continuous/dac_audio`
*
* @param[in] handle The DAC continuous channel handle that obtained from 'dac_continuous_new_channels'
* @param[in] dma_buf The DMA buffer address, it can be acquired from 'dac_event_data_t' in the 'on_convert_done' callback
* @param[in] dma_buf_len The DMA buffer length, it can be acquired from 'dac_event_data_t' in the 'on_convert_done' callback
* @param[in] data The data that need to be written
* @param[in] data_len The data length the need to be written
* @param[out] bytes_loaded The bytes number that has been loaded/written into the DMA buffer
* @return
* - ESP_OK Write the data into DMA buffer successfully
* - ESP_ERR_INVALID_ARG NULL pointer
* - ESP_ERR_INVALID_STATE The channels haven't start the asynchronous writing
* - ESP_ERR_NOT_FOUND The param 'dam_buf' not match any existed DMA buffer
*/
esp_err_t dac_continuous_write_asynchronously(dac_continuous_handle_t handle,
uint8_t *dma_buf,
size_t dma_buf_len,
const uint8_t *data,
size_t data_len,
size_t *bytes_loaded);
#endif // SOC_DAC_SUPPORTED
#ifdef __cplusplus
}
#endif