components/esp_driver_dac/include/driver/dac_continuous.h (ESP-IDF)

Outline

#include "driver/dac_types.h"

#include "esp_err.h"

dac_channel_mask_t

dac_continuous_s

dac_continuous_config_t

dac_event_data_t

dac_isr_callback_t

dac_event_callbacks_t

dac_continuous_new_channels(const dac_continuous_config_t *, dac_continuous_handle_t *);

dac_continuous_del_channels(dac_continuous_handle_t);

dac_continuous_enable(dac_continuous_handle_t);

dac_continuous_disable(dac_continuous_handle_t);

dac_continuous_write(dac_continuous_handle_t, uint8_t *, size_t, size_t *, int);

dac_continuous_write_cyclically(dac_continuous_handle_t, uint8_t *, size_t, size_t *);

dac_continuous_register_event_callback(dac_continuous_handle_t, const dac_event_callbacks_t *, void *);

dac_continuous_start_async_writing(dac_continuous_handle_t);

dac_continuous_stop_async_writing(dac_continuous_handle_t);

dac_continuous_write_asynchronously(dac_continuous_handle_t, uint8_t *, size_t, const uint8_t *, size_t, size_t *);

Files

SourceVuESP-IDF Framework and ExamplesESP-IDFcomponents/esp_driver_dac/include/driver/dac_continuous.h

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

/* * 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

Details