1 /** 2 * @file dma.h 3 * @brief Direct Memory Access (DMA) driver function prototypes and data types. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32520_DMA_H_ 27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32520_DMA_H_ 28 29 /* **** Includes **** */ 30 #include <stdbool.h> 31 #include "mxc_device.h" 32 #include "dma_regs.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * @defgroup dma Direct Memory Access (DMA) 40 * @ingroup periphlibs 41 * @{ 42 */ 43 44 /* **** Definitions **** */ 45 46 /** 47 * @brief Enumeration for the DMA Channel's priority level. 48 * 49 */ 50 typedef enum { 51 MXC_DMA_PRIO_HIGH = MXC_V_DMA_CFG_PRI_HIGH, ///< High Priority 52 MXC_DMA_PRIO_MEDHIGH = MXC_V_DMA_CFG_PRI_MEDHIGH, ///< Medium High Priority 53 MXC_DMA_PRIO_MEDLOW = MXC_V_DMA_CFG_PRI_MEDLOW, ///< Medium Low Priority 54 MXC_DMA_PRIO_LOW = MXC_V_DMA_CFG_PRI_LOW, ///< Low Priority 55 } mxc_dma_priority_t; 56 57 /** @brief DMA request select */ 58 typedef enum { 59 MXC_DMA_REQUEST_MEMTOMEM = 60 MXC_S_DMA_CFG_REQSEL_MEMTOMEM, ///< Memory to Memory DMA Request Selection 61 MXC_DMA_REQUEST_SPI0RX = MXC_S_DMA_CFG_REQSEL_SPI0RX, ///< SPI0 Receive DMA Request Selection 62 MXC_DMA_REQUEST_SPI1RX = MXC_S_DMA_CFG_REQSEL_SPI1RX, ///< SPI1 Receive DMA Request Selection 63 MXC_DMA_REQUEST_UART0RX = MXC_S_DMA_CFG_REQSEL_UART0RX, ///< UART0 Receive DMA Request Selection 64 MXC_DMA_REQUEST_I2C0RX = MXC_S_DMA_CFG_REQSEL_I2C0RX, ///< I2C0 Receive DMA Request Selection 65 MXC_DMA_REQUEST_SPI0TX = MXC_S_DMA_CFG_REQSEL_SPI0TX, ///< SPI0 Transmit DMA Request Selection 66 MXC_DMA_REQUEST_SPI1TX = MXC_S_DMA_CFG_REQSEL_SPI1TX, ///< SPI1 Transmit DMA Request Selection 67 MXC_DMA_REQUEST_UART0TX = 68 MXC_S_DMA_CFG_REQSEL_UART0TX, ///< UART0 Transmit DMA Request Selection 69 MXC_DMA_REQUEST_I2C0TX = MXC_S_DMA_CFG_REQSEL_I2C0TX, ///< I2C0 Transmit DMA Request Selection 70 } mxc_dma_reqsel_t; 71 72 /** @brief Enumeration for the DMA prescaler */ 73 typedef enum { 74 MXC_DMA_PRESCALE_DISABLE = MXC_S_DMA_CFG_PSSEL_DIS, ///< Prescaler disabled 75 MXC_DMA_PRESCALE_DIV256 = MXC_S_DMA_CFG_PSSEL_DIV256, ///< Divide by 256 76 MXC_DMA_PRESCALE_DIV64K = MXC_S_DMA_CFG_PSSEL_DIV64K, ///< Divide by 65,536 77 MXC_DMA_PRESCALE_DIV16M = MXC_S_DMA_CFG_PSSEL_DIV16M, ///< Divide by 16,777,216 78 } mxc_dma_prescale_t; 79 80 /** @brief Enumeration for the DMA timeout value */ 81 typedef enum { 82 MXC_DMA_TIMEOUT_4_CLK = MXC_S_DMA_CFG_TOSEL_TO4, ///< DMA timeout of 4 clocks 83 MXC_DMA_TIMEOUT_8_CLK = MXC_S_DMA_CFG_TOSEL_TO8, ///< DMA timeout of 8 clocks 84 MXC_DMA_TIMEOUT_16_CLK = MXC_S_DMA_CFG_TOSEL_TO16, ///< DMA timeout of 16 clocks 85 MXC_DMA_TIMEOUT_32_CLK = MXC_S_DMA_CFG_TOSEL_TO32, ///< DMA timeout of 32 clocks 86 MXC_DMA_TIMEOUT_64_CLK = MXC_S_DMA_CFG_TOSEL_TO64, ///< DMA timeout of 64 clocks 87 MXC_DMA_TIMEOUT_128_CLK = MXC_S_DMA_CFG_TOSEL_TO128, ///< DMA timeout of 128 clocks 88 MXC_DMA_TIMEOUT_256_CLK = MXC_S_DMA_CFG_TOSEL_TO256, ///< DMA timeout of 256 clocks 89 MXC_DMA_TIMEOUT_512_CLK = MXC_S_DMA_CFG_TOSEL_TO512, ///< DMA timeout of 512 clocks 90 } mxc_dma_timeout_t; 91 92 /** @brief DMA transfer data width */ 93 typedef enum { 94 /* Using the '_V_' define instead of the '_S_' since these same values will be used to 95 specify the DSTWD also. The API functions will shift the value the correct amount 96 prior to writing the cfg register. */ 97 MXC_DMA_WIDTH_BYTE = MXC_V_DMA_CFG_SRCWD_BYTE, ///< DMA transfer in bytes 98 MXC_DMA_WIDTH_HALFWORD = MXC_V_DMA_CFG_SRCWD_HALFWORD, ///< DMA transfer in 16-bit half-words 99 MXC_DMA_WIDTH_WORD = MXC_V_DMA_CFG_SRCWD_WORD, ///< DMA transfer in 32-bit words 100 } mxc_dma_width_t; 101 102 /** 103 * @brief The basic configuration information to set up a DMA channel 104 * and prepare it for transfers. 105 * 106 */ 107 typedef struct { 108 int ch; ///< The channel to load the configuration data into 109 mxc_dma_reqsel_t reqsel; ///< The request select line to be used (mem2mem, peripheral) 110 mxc_dma_width_t srcwd; ///< The source width (could be dependent on FIFO width) 111 mxc_dma_width_t dstwd; ///< The destination width (could be dependent on FIFO width) 112 int srcinc_en; ///< Whether to increment the source address during the transfer 113 int dstinc_en; ///< Whether to increment the source address during the transfer 114 } mxc_dma_config_t; 115 116 /** 117 * @brief The information needed to complete a DMA transfer 118 * 119 */ 120 typedef struct { 121 int ch; ///< The channel to use for the transfer 122 void *source; ///< Pointer to the source address, if applicable 123 void *dest; ///< Pointer to the destination address, if applicable 124 int len; ///< Number of bytes to transfer 125 } mxc_dma_srcdst_t; 126 127 /** 128 * @brief The advanced configuration options, these are optional but could 129 * be needed in cases where multiple DMA channels are running concurrently 130 * or DMA is being used with low bandwidth peripherals. 131 * 132 */ 133 typedef struct { 134 int ch; ///< The channel to use for the transfer 135 mxc_dma_priority_t prio; ///< The DMA priority for the channel 136 unsigned int reqwait_en; ///< Delay the timeout timer start until after first transfer 137 mxc_dma_timeout_t tosel; ///< Number of prescaled clocks seen by the channel before a timeout 138 mxc_dma_prescale_t pssel; ///< Prescaler for the timeout timer 139 unsigned int burst_size; ///< Number of bytes moved in a single burst 140 } mxc_dma_adv_config_t; 141 142 /** 143 * @brief The callback called on completion of a DMA_MemCpy() transfer 144 * 145 * @param dest Pointer to the destination of the copy 146 */ 147 typedef void (*mxc_dma_complete_cb_t)(void *dest); 148 149 /** 150 * @brief The callback called on completion of a transfer, 151 * @note This callback is used with MXC_DMA_DoTransfer() 152 * to allow the user to chain an unlimited number of 153 * DMA Transfers. 154 * 155 * @param trans Struct of the completed transfer 156 * 157 * @return Returns the next transfer to be completed, or NULL 158 * if no more transfers will be done 159 */ 160 typedef mxc_dma_srcdst_t (*mxc_dma_trans_chain_t)(mxc_dma_srcdst_t dest); 161 162 /* **** Function Prototypes **** */ 163 164 /*************************/ 165 /* Low Level Functions */ 166 /*************************/ 167 168 /** 169 * @brief Initialize DMA resources 170 * @details This initialization is required before using the DMA driver functions. 171 * @note On default this function enables DMA peripheral clock. 172 * if you wish to manage clock and gpio related things in upper level instead of here. 173 * Define MSDK_NO_GPIO_CLK_INIT flag in project.mk file. 174 * By this flag this function will remove clock and gpio related codes from file. 175 * @return #E_NO_ERROR if successful 176 */ 177 int MXC_DMA_Init(void); 178 179 /** 180 * @brief De-Initialize DMA resources. 181 */ 182 void MXC_DMA_DeInit(void); 183 184 /** 185 * @brief Request DMA channel 186 * @details Returns a handle to the first free DMA channel, which can be used via API calls 187 * or direct access to channel registers using the MXC_DMA_GetCHRegs(int ch) function. 188 * @return Non-negative channel handle (inclusive of zero). 189 * @return #E_NONE_AVAIL All channels in use. 190 * @return #E_BAD_STATE DMA is not initialized, call MXC_DMA_Init() first. 191 * @return #E_BUSY DMA is currently busy (locked), try again later. 192 */ 193 int MXC_DMA_AcquireChannel(void); 194 195 /** 196 * @brief Release DMA channel 197 * @details Stops any DMA operation on the channel and returns it to the pool of free channels. 198 * 199 * @param ch channel handle to release 200 * 201 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 202 */ 203 int MXC_DMA_ReleaseChannel(int ch); 204 205 /** 206 * @brief Configure the DMA channel 207 * @details Configures the channel, which was previously requested by MXC_DMA_Getchannel() 208 * 209 * @param config Struct containing DMA configuration parameters 210 * @param srcdst Struct containing pointers and length of DMA operation 211 * 212 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 213 */ 214 int MXC_DMA_ConfigChannel(mxc_dma_config_t config, mxc_dma_srcdst_t srcdst); 215 216 /** 217 * @brief Configure the DMA channel with more advanced parameters 218 * 219 * @param advConfig Struct containing advanced DMA parameters 220 * 221 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 222 */ 223 int MXC_DMA_AdvConfigChannel(mxc_dma_adv_config_t advConfig); 224 225 /** 226 * @brief Set channel source, destination, and count for the transfer 227 * @param srcdst Struct containing the channel, source, destination, and count for the channel 228 * @note Unless the channel request select is #mxc_dma_srcdst_t = MXC_DMA_REQUEST_MEMTOMEM, 229 * either src_addr or dst_addr will be ignored by the DMA engine. 230 * In these cases, the address is a don't-care. See the User's 231 * Guide for more information. 232 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 233 */ 234 int MXC_DMA_SetSrcDst(mxc_dma_srcdst_t srcdst); 235 236 /** 237 * @brief Get channel source, destination, and count for transfer 238 * 239 * @param srcdst Pointer to struct with the correct channel number 240 * 241 * @return See \ref MXC_Error_Codes for a list of return values 242 */ 243 int MXC_DMA_GetSrcDst(mxc_dma_srcdst_t *srcdst); 244 245 /** 246 * @brief Set channel reload source, destination, and count for the transfer 247 * @param srcdstReload Struct containing the channel, source, destination, and count for the channel 248 * @note Unless the channel request select is #mxc_dma_srcdst_t = MXC_DMA_REQUEST_MEMTOMEM, 249 * either src_addr or dst_addr will be ignored by the DMA engine. 250 * In these cases, the address is a don't-care. See the User's 251 * Guide for more information. 252 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 253 */ 254 int MXC_DMA_SetSrcReload(mxc_dma_srcdst_t srcdstReload); 255 256 /** 257 * @brief Get channel reload source, destination, and count for transfer 258 * 259 * @param srcdstReload Pointer to struct with the correct channel number 260 * 261 * @return See \ref MXC_Error_Codes for a list of return values 262 */ 263 int MXC_DMA_GetSrcReload(mxc_dma_srcdst_t *srcdstReload); 264 265 /** 266 * @brief Set channel interrupt callback 267 * @param ch channel handle 268 * @param callback Pointer to a function to call when the channel 269 * interrupt flag is set and interrupts are enabled or 270 * when DMA is shutdown by the driver. 271 * @details Configures the channel interrupt callback. The @p callback 272 * function is called for two conditions: 273 * -# When the channel's interrupt flag is set and DMA interrupts 274 * are enabled. 275 * -# If the driver calls the MXC_DMA_Shutdown() function. The 276 * callback function prototype is: 277 * @code 278 * void callback_fn(int ch, int reason); 279 * @endcode 280 * @p ch indicates the channel that generated the callback, @p 281 * reason is either #E_NO_ERROR for a DMA interrupt or #E_SHUTDOWN 282 * if the DMA is being shutdown. 283 * 284 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR 285 * otherwise 286 */ 287 int MXC_DMA_SetCallback(int ch, void (*callback)(int, int)); 288 289 /** 290 * @brief Set channel interrupt 291 * @note Each channel has two interrupts (complete, and count to zero). 292 * To enable complete, pass true for chdis. To enable count to zero, 293 * pass true for ctz. 294 * @param ch Channel Handle 295 * @param chdis Enable channel complete interrupt 296 * @param ctz Enable channel count to zero interrupt. 297 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 298 */ 299 int MXC_DMA_SetChannelInterruptEn(int ch, bool chdis, bool ctz); 300 301 /** 302 * @brief Enable channel interrupt 303 * @note Each channel has two interrupts (complete, and count to zero) 304 which must also be enabled with MXC_DMA_SetChannelInterruptEn() 305 * @param ch channel handle 306 * @param flags The flags to enable 307 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 308 */ 309 int MXC_DMA_ChannelEnableInt(int ch, int flags); 310 311 /** 312 * @brief Disable channel interrupt 313 * @param ch channel handle 314 * @param flags The flags to disable 315 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 316 */ 317 int MXC_DMA_ChannelDisableInt(int ch, int flags); 318 319 /** 320 * @brief Read channel interrupt flags 321 * @param ch channel handle 322 * @return #E_BAD_PARAM if an unused or invalid channel handle, flags otherwise 323 */ 324 int MXC_DMA_ChannelGetFlags(int ch); 325 326 /** 327 * @brief Clear channel interrupt flags 328 * @param ch channel handle 329 * @param flags The flags to clear 330 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 331 */ 332 int MXC_DMA_ChannelClearFlags(int ch, int flags); 333 334 /** 335 * @brief Enable channel interrupt 336 * @note Each channel has two interrupts (complete, and count to zero) 337 which must also be enabled with MXC_DMA_SetChannelInterruptEn() 338 * @param ch channel handle 339 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 340 */ 341 int MXC_DMA_EnableInt(int ch); 342 343 /** 344 * @brief Disable channel interrupt 345 * @param ch channel handle 346 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 347 */ 348 int MXC_DMA_DisableInt(int ch); 349 350 /** 351 * @brief Start transfer 352 * @param ch channel handle 353 * @details Start the DMA channel transfer, assumes that MXC_DMA_SetSrcDstCnt() has been called beforehand. 354 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 355 */ 356 int MXC_DMA_Start(int ch); 357 358 /** 359 * @brief Stop DMA transfer, irrespective of status (complete or in-progress) 360 * @param ch channel handle 361 * @return #E_BAD_PARAM if an unused or invalid channel handle, #E_NO_ERROR otherwise 362 */ 363 int MXC_DMA_Stop(int ch); 364 365 /** 366 * @brief Get a pointer to the DMA channel registers 367 * @param ch channel handle 368 * @details If direct access to DMA channel registers is required, this 369 * function can be used on a channel handle returned by MXC_DMA_AcquireChannel(). 370 * @return NULL if an unused or invalid channel handle, or a valid pointer otherwise 371 */ 372 mxc_dma_ch_regs_t *MXC_DMA_GetCHRegs(int ch); 373 374 /** 375 * @brief Interrupt handler function 376 * @details Call this function as the ISR for each DMA channel under driver control. 377 * Interrupt flags for channel ch will be automatically cleared before return. 378 */ 379 void MXC_DMA_Handler(void); 380 381 /*************************/ 382 /* High Level Functions */ 383 /*************************/ 384 385 /** 386 * @brief Performs a memcpy, using DMA, optionally asynchronous 387 * @note The user must have the DMA interrupt enabled and call 388 * MXC_DMA_Handler() from the ISR. 389 * 390 * @param dest pointer to destination memory 391 * @param src pointer to source memory 392 * @param len number of bytes to copy 393 * @param callback function to call when transfer is complete 394 * 395 * @return see \ref MXC_Error_Codes 396 */ 397 int MXC_DMA_MemCpy(void *dest, void *src, int len, mxc_dma_complete_cb_t callback); 398 399 /** 400 * @brief Performs a memcpy, using DMA, optionally asynchronous 401 * @note The user must have the DMA interrupt enabled and call 402 * MXC_DMA_Handler() from the ISR. 403 * 404 * @param config The channel config struct 405 * @param firstSrcDst The source, destination, and count for the first transfer 406 * @param callback function is called when transfer is complete 407 * 408 * @return see \ref MXC_Error_Codes 409 */ 410 int MXC_DMA_DoTransfer(mxc_dma_config_t config, mxc_dma_srcdst_t firstSrcDst, 411 mxc_dma_trans_chain_t callback); 412 /** 413 * For other functional uses of DMA (UART, SPI, etc) see the appropriate peripheral driver 414 */ 415 416 /**@} end of group dma */ 417 #ifdef __cplusplus 418 } 419 #endif 420 421 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32520_DMA_H_ 422
