1 /** 2 * @file uart.h 3 * @brief Serial Peripheral Interface (UART) communications driver. 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 /* Define to prevent redundant inclusion */ 27 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32572_UART_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32572_UART_H_ 29 30 /***** Definitions *****/ 31 #include <stdbool.h> 32 #include "uart_regs.h" 33 #include "mxc_sys.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 #define UART_EXTCLK_FREQ E_BAD_PARAM 40 41 /** 42 * @defgroup uart UART 43 * @ingroup periphlibs 44 * @{ 45 */ 46 47 typedef struct _mxc_uart_req_t mxc_uart_req_t; 48 /** 49 * @brief The list of UART stop bit lengths supported 50 * 51 */ 52 typedef enum { 53 MXC_UART_STOP_1, ///< UART Stop 1 clock cycle 54 MXC_UART_STOP_2, ///< UART Stop 2 clock cycle (1.5 clocks for 5 bit characters) 55 } mxc_uart_stop_t; 56 57 /** 58 * @brief The list of UART Parity options supported 59 * 60 */ 61 typedef enum { 62 MXC_UART_PARITY_DISABLE, ///< UART Parity Disabled 63 MXC_UART_PARITY_EVEN_0, ///< UART Parity Even, 0 based 64 MXC_UART_PARITY_EVEN_1, ///< UART Parity Even, 1 based 65 MXC_UART_PARITY_ODD_0, ///< UART Parity Odd, 0 based 66 MXC_UART_PARITY_ODD_1, ///< UART Parity Odd, 1 based 67 } mxc_uart_parity_t; 68 69 /** 70 * @brief The list of UART flow control options supported 71 * 72 */ 73 typedef enum { 74 MXC_UART_FLOW_DIS, ///< UART Flow Control Disabled 75 MXC_UART_FLOW_EN, ///< UART Flow Control Enabled 76 } mxc_uart_flow_t; 77 78 /** 79 * @brief Clock settings */ 80 typedef enum { 81 /*For UART3 APB clock source is the 8MHz clock*/ 82 MXC_UART_APB_CLK = 0, 83 MXC_UART_EXT_CLK = 1, 84 /*IBRO and ERFO clock can only be used for UART 0, 1 & 2*/ 85 MXC_UART_IBRO_CLK = 2, 86 MXC_UART_ERFO_CLK = 3, 87 /*ERTCO clock can only be used for UART3*/ 88 MXC_UART_ERTCO_CLK = 4, 89 } mxc_uart_clock_t; 90 91 /** 92 * @brief The callback routine used to indicate the transaction has terminated. 93 * 94 * @param req The details of the transaction. 95 * @param result See \ref MXC_Error_Codes for the list of error codes. 96 */ 97 typedef void (*mxc_uart_complete_cb_t)(mxc_uart_req_t *req, int result); 98 99 /** 100 * @brief The callback routine used to indicate the transaction has terminated. 101 * 102 * @param req The details of the transaction. 103 * @param num The number of characters actually copied 104 * @param result See \ref MXC_Error_Codes for the list of error codes. 105 */ 106 typedef void (*mxc_uart_dma_complete_cb_t)(mxc_uart_req_t *req, int num, int result); 107 108 /** 109 * @brief The information required to perform a complete UART transaction 110 * 111 * @note This structure is used by blocking, async, and DMA based transactions. 112 * @note "callback" only needs to be initialized for interrupt driven (Async) and DMA transactions. 113 */ 114 struct _mxc_uart_req_t { 115 mxc_uart_regs_t *uart; ///<Point to UART registers 116 const uint8_t *txData; ///< Buffer containing transmit data. For character sizes 117 ///< < 8 bits, pad the MSB of each byte with zeros. For 118 ///< character sizes > 8 bits, use two bytes per character 119 ///< and pad the MSB of the upper byte with zeros 120 uint8_t *rxData; ///< Buffer to store received data For character sizes 121 ///< < 8 bits, pad the MSB of each byte with zeros. For 122 ///< character sizes > 8 bits, use two bytes per character 123 ///< and pad the MSB of the upper byte with zeros 124 uint32_t txLen; ///< Number of bytes to be sent from txData 125 uint32_t rxLen; ///< Number of bytes to be stored in rxData 126 uint32_t txCnt; ///< Number of bytes actually transmitted from txData 127 uint32_t rxCnt; ///< Number of bytes stored in rxData 128 129 mxc_uart_complete_cb_t callback; ///< Pointer to function called when transaction is complete 130 }; 131 132 /***** Function Prototypes *****/ 133 134 /* ************************************************************************* */ 135 /* Control/Configuration functions */ 136 /* ************************************************************************* */ 137 138 /** 139 * @brief Initialize and enable UART peripheral. 140 * 141 * This function initializes everything necessary to call a UART transaction function. 142 * Some parameters are set to defaults as follows: 143 * UART Data Size - 8 bits 144 * UART Stop Bits - 1 bit 145 * UART Parity - None 146 * UART Flow Control - None 147 * 148 * These parameters can be modified after initialization using low level functions 149 * 150 * @param uart Pointer to UART registers (selects the UART block used.) 151 * @param baud The requested clock frequency. The actual clock frequency 152 * will be returned by the function if successful. 153 * @param clock Clock source 154 * 155 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 156 */ 157 int MXC_UART_Init(mxc_uart_regs_t *uart, unsigned int baud, mxc_uart_clock_t clock); 158 159 /** 160 * @brief Disable and shutdown UART peripheral. 161 * 162 * @param uart Pointer to UART registers (selects the UART block used.) 163 * 164 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 165 */ 166 int MXC_UART_Shutdown(mxc_uart_regs_t *uart); 167 168 /** 169 * @brief Checks if the given UART bus can be placed in sleep more. 170 * 171 * @note This functions checks to see if there are any on-going UART transactions in 172 * progress. If there are transactions in progress, the application should 173 * wait until the UART bus is free before entering a low-power state. 174 * 175 * @param uart Pointer to UART registers (selects the UART block used.) 176 * 177 * @return #E_NO_ERROR if ready, and non-zero if busy or error. See \ref 178 * MXC_Error_Codes for the list of error return codes. 179 */ 180 int MXC_UART_ReadyForSleep(mxc_uart_regs_t *uart); 181 182 /** 183 * @brief Set the frequency of the UART interface. 184 * 185 * @param uart Pointer to UART registers (selects the UART block used.) 186 * @param baud The desired baud rate 187 * @param clock Clock source 188 * 189 * @return Negative if error, otherwise actual speed set. See \ref 190 * MXC_Error_Codes for the list of error return codes. 191 */ 192 int MXC_UART_SetFrequency(mxc_uart_regs_t *uart, unsigned int baud, mxc_uart_clock_t clock); 193 194 /** 195 * @brief Get the frequency of the UART interface. 196 * 197 * @note This function is applicable in Master mode only 198 * 199 * @param uart Pointer to UART registers (selects the UART block used.) 200 * 201 * @return The UART baud rate 202 */ 203 int MXC_UART_GetFrequency(mxc_uart_regs_t *uart); 204 205 /** 206 * @brief Sets the number of bits per character 207 * 208 * @param uart Pointer to UART registers (selects the UART block used.) 209 * @param dataSize The number of bits per character (5-8 bits/character are valid) 210 * 211 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 212 */ 213 int MXC_UART_SetDataSize(mxc_uart_regs_t *uart, int dataSize); 214 215 /** 216 * @brief Sets the number of stop bits sent at the end of a character 217 * 218 * @param uart Pointer to UART registers (selects the UART block used.) 219 * @param stopBits The number of stop bits used 220 * 221 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 222 */ 223 int MXC_UART_SetStopBits(mxc_uart_regs_t *uart, mxc_uart_stop_t stopBits); 224 225 /** 226 * @brief Sets the type of parity generation used 227 * 228 * @param uart Pointer to UART registers (selects the UART block used.) 229 * @param parity see \ref UART Parity Types for details 230 * 231 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 232 */ 233 int MXC_UART_SetParity(mxc_uart_regs_t *uart, mxc_uart_parity_t parity); 234 235 /** 236 * @brief Sets the flow control used 237 * 238 * @param uart Pointer to UART registers (selects the UART block used.) 239 * @param flowCtrl see \ref UART Flow Control Types for details 240 * @param rtsThreshold Number of bytes remaining in the RX FIFO when RTS is asserted 241 * 242 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 243 */ 244 int MXC_UART_SetFlowCtrl(mxc_uart_regs_t *uart, mxc_uart_flow_t flowCtrl, int rtsThreshold); 245 246 /** 247 * @brief Sets the clock source for the baud rate generator 248 * 249 * @param uart Pointer to UART registers (selects the UART block used.) 250 * @param clock Clock source 251 * 252 * @return Actual baud rate if successful, otherwise see \ref MXC_Error_Codes 253 * for a list of return codes. 254 */ 255 int MXC_UART_SetClockSource(mxc_uart_regs_t *uart, mxc_uart_clock_t clock); 256 257 /* ************************************************************************* */ 258 /* Low-level functions */ 259 /* ************************************************************************* */ 260 261 /** 262 * @brief Checks the UART Peripheral for an ongoing transmission 263 * 264 * @note This function is applicable in Master mode only 265 * 266 * @param uart Pointer to UART registers (selects the UART block used.) 267 * 268 * @return Active/Inactive, see \ref MXC_Error_Codes for a list of return codes. 269 */ 270 int MXC_UART_GetActive(mxc_uart_regs_t *uart); 271 272 /** 273 * @brief Aborts an ongoing UART Transmission 274 * 275 * @param uart Pointer to UART registers (selects the UART block used.) 276 * 277 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 278 */ 279 int MXC_UART_AbortTransmission(mxc_uart_regs_t *uart); 280 281 /** 282 * @brief Reads the next available character. If no character is available, this function 283 * will return an error. 284 * 285 * @param uart Pointer to UART registers (selects the UART block used.) 286 * 287 * @return The character read, otherwise see \ref MXC_Error_Codes for a list of return codes. 288 */ 289 int MXC_UART_ReadCharacterRaw(mxc_uart_regs_t *uart); 290 291 /** 292 * @brief Writes a character on the UART. If the character cannot be written because the 293 * transmit FIFO is currently full, this function returns an error. 294 * 295 * @param uart Pointer to UART registers (selects the UART block used.) 296 * @param character The character to write 297 * 298 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 299 */ 300 int MXC_UART_WriteCharacterRaw(mxc_uart_regs_t *uart, uint8_t character); 301 302 /** 303 * @brief Reads the next available character 304 * 305 * @param uart Pointer to UART registers (selects the UART block used.) 306 * 307 * @return The character read, otherwise see \ref MXC_Error_Codes for a list of return codes. 308 */ 309 int MXC_UART_ReadCharacter(mxc_uart_regs_t *uart); 310 311 /** 312 * @brief Writes a character on the UART 313 * 314 * @param uart Pointer to UART registers (selects the UART block used.) 315 * @param character The character to write 316 * 317 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 318 */ 319 int MXC_UART_WriteCharacter(mxc_uart_regs_t *uart, uint8_t character); 320 321 /** 322 * @brief Reads the next available character 323 * @note This function blocks until len characters are received 324 * See MXC_UART_TransactionAsync() for a non-blocking version 325 * 326 * @param uart Pointer to UART registers (selects the UART block used.) 327 * @param buffer Buffer to store data in 328 * @param len Number of characters 329 * 330 * @return The character read, otherwise see \ref MXC_Error_Codes for a list of return codes. 331 */ 332 int MXC_UART_Read(mxc_uart_regs_t *uart, uint8_t *buffer, int *len); 333 334 /** 335 * @brief Writes a byte on the UART 336 * 337 * @param uart Pointer to UART registers (selects the UART block used.) 338 * @param byte The buffer of characters to write 339 * @param len The number of characters to write 340 * 341 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 342 */ 343 int MXC_UART_Write(mxc_uart_regs_t *uart, const uint8_t *byte, int *len); 344 345 /** 346 * @brief Unloads bytes from the receive FIFO. 347 * 348 * @param uart Pointer to UART registers (selects the UART block used.) 349 * @param bytes The buffer to read the data into. 350 * @param len The number of bytes to read. 351 * 352 * @return The number of bytes actually read. 353 */ 354 unsigned int MXC_UART_ReadRXFIFO(mxc_uart_regs_t *uart, unsigned char *bytes, unsigned int len); 355 356 /** 357 * @brief Unloads bytes from the receive FIFO user DMA for longer reads. 358 * 359 * @param uart Pointer to UART registers (selects the UART block used.) 360 * @param bytes The buffer to read the data into. 361 * @param len The number of bytes to read. 362 * @param callback The function to call when the read is complete 363 * 364 * @return See \ref MXC_ERROR_CODES for a list of return values 365 */ 366 int MXC_UART_ReadRXFIFODMA(mxc_uart_regs_t *uart, unsigned char *bytes, unsigned int len, 367 mxc_uart_dma_complete_cb_t callback); 368 369 /** 370 * @brief Get the number of bytes currently available in the receive FIFO. 371 * 372 * @param uart Pointer to UART registers (selects the UART block used.) 373 * 374 * @return The number of bytes available. 375 */ 376 unsigned int MXC_UART_GetRXFIFOAvailable(mxc_uart_regs_t *uart); 377 378 /** 379 * @brief Loads bytes into the transmit FIFO. 380 * 381 * @param uart Pointer to UART registers (selects the UART block used.) 382 * @param bytes The buffer containing the bytes to write 383 * @param len The number of bytes to write. 384 * 385 * @return The number of bytes actually written. 386 */ 387 unsigned int MXC_UART_WriteTXFIFO(mxc_uart_regs_t *uart, const unsigned char *bytes, 388 unsigned int len); 389 390 /** 391 * @brief Loads bytes into the transmit FIFO using DMA for longer writes 392 * 393 * @param uart Pointer to UART registers (selects the UART block used.) 394 * @param bytes The buffer containing the bytes to write 395 * @param len The number of bytes to write. 396 * @param callback The function to call when the write is complete 397 * 398 * @return See \ref MXC_ERROR_CODES for a list of return values 399 */ 400 int MXC_UART_WriteTXFIFODMA(mxc_uart_regs_t *uart, const unsigned char *bytes, unsigned int len, 401 mxc_uart_dma_complete_cb_t callback); 402 403 /** 404 * @brief Get the amount of free space available in the transmit FIFO. 405 * 406 * @param uart Pointer to UART registers (selects the UART block used.) 407 * 408 * @return The number of bytes available. 409 */ 410 unsigned int MXC_UART_GetTXFIFOAvailable(mxc_uart_regs_t *uart); 411 412 /** 413 * @brief Removes and discards all bytes currently in the receive FIFO. 414 * 415 * @param uart Pointer to UART registers (selects the UART block used.) 416 * 417 * @return See \ref MXC_Error_Codes for the list of error return codes. 418 */ 419 int MXC_UART_ClearRXFIFO(mxc_uart_regs_t *uart); 420 421 /** 422 * @brief Removes and discards all bytes currently in the transmit FIFO. 423 * 424 * @param uart Pointer to UART registers (selects the UART block used.) 425 * 426 * @return See \ref MXC_Error_Codes for the list of error return codes. 427 */ 428 int MXC_UART_ClearTXFIFO(mxc_uart_regs_t *uart); 429 430 /** 431 * @brief Set the receive threshold level. 432 * 433 * @note RX FIFO Receive threshold. Smaller values will cause 434 * interrupts to occur more often, but reduce the possibility 435 * of losing data because of a FIFO overflow. Larger values 436 * will reduce the time required by the ISR, but increase the 437 * possibility of data loss. Passing an invalid value will 438 * cause the driver to use the value already set in the 439 * appropriate register. 440 * 441 * @param uart Pointer to UART registers (selects the UART block used.) 442 * @param numBytes The threshold level to set. This value must be 443 * between 0 and 8 inclusive. 444 * 445 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 446 */ 447 int MXC_UART_SetRXThreshold(mxc_uart_regs_t *uart, unsigned int numBytes); 448 449 /** 450 * @brief Get the current receive threshold level. 451 * 452 * @param uart Pointer to UART registers (selects the UART block used.) 453 * 454 * @return The receive threshold value (in bytes). 455 */ 456 unsigned int MXC_UART_GetRXThreshold(mxc_uart_regs_t *uart); 457 458 /** 459 * @brief Set the transmit threshold level. 460 * 461 * @note TX FIFO threshold. Smaller values will cause interrupts 462 * to occur more often, but reduce the possibility of terminating 463 * a transaction early in master mode, or transmitting invalid data 464 * in slave mode. Larger values will reduce the time required by 465 * the ISR, but increase the possibility errors occurring. Passing 466 * an invalid value will cause the driver to use the value already 467 * set in the appropriate register. 468 * 469 * @param uart Pointer to UART registers (selects the UART block used.) 470 * @param numBytes The threshold level to set. This value must be 471 * between 0 and 8 inclusive. 472 * 473 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 474 */ 475 int MXC_UART_SetTXThreshold(mxc_uart_regs_t *uart, unsigned int numBytes); 476 477 /** 478 * @brief Get the current transmit threshold level. 479 * 480 * @param uart Pointer to UART registers (selects the UART block used.) 481 * 482 * @return The transmit threshold value (in bytes). 483 */ 484 unsigned int MXC_UART_GetTXThreshold(mxc_uart_regs_t *uart); 485 486 /** 487 * @brief Gets the interrupt flags that are currently set 488 * 489 * @note These functions should not be used while using non-blocking Transaction Level 490 * functions (Async or DMA) 491 * 492 * @param uart Pointer to UART registers (selects the UART block used.) 493 * 494 * @return The interrupt flags 495 */ 496 unsigned int MXC_UART_GetFlags(mxc_uart_regs_t *uart); 497 498 /** 499 * @brief Clears the interrupt flags that are currently set 500 * 501 * @note These functions should not be used while using non-blocking Transaction Level 502 * functions (Async or DMA) 503 * 504 * @param uart Pointer to UART registers (selects the UART block used.) 505 * @param flags mask of flags to clear 506 * 507 * @return See \ref MXC_Error_Codes for the list of error return codes. 508 */ 509 int MXC_UART_ClearFlags(mxc_uart_regs_t *uart, unsigned int flags); 510 511 /** 512 * @brief Enables specific interrupts 513 * 514 * @note These functions should not be used while using non-blocking Transaction Level 515 * functions (Async or DMA) 516 * 517 * @param uart Pointer to UART registers (selects the UART block used.) 518 * @param mask The interrupts to be enabled 519 * 520 * @return See \ref MXC_Error_Codes for the list of error return codes. 521 */ 522 int MXC_UART_EnableInt(mxc_uart_regs_t *uart, unsigned int mask); 523 524 /** 525 * @brief Disables specific interrupts 526 * 527 * @note These functions should not be used while using non-blocking Transaction Level 528 * functions (Async or DMA) 529 * 530 * @param uart Pointer to UART registers (selects the UART block used.) 531 * @param mask The interrupts to be disabled 532 * 533 * @return See \ref MXC_Error_Codes for the list of error return codes. 534 */ 535 int MXC_UART_DisableInt(mxc_uart_regs_t *uart, unsigned int mask); 536 537 /** 538 * @brief Gets the status flags that are currently set 539 * 540 * @param uart Pointer to UART registers (selects the UART block used.) 541 * 542 * @return The status flags 543 */ 544 unsigned int MXC_UART_GetStatus(mxc_uart_regs_t *uart); 545 546 /* ************************************************************************* */ 547 /* Transaction level functions */ 548 /* ************************************************************************* */ 549 550 /** 551 * @brief Performs a blocking UART transaction. 552 * 553 * @note Performs a blocking UART transaction as follows. 554 * If tx_len is non-zero, transmit TX data 555 * Once tx_len has been sent, if rx_len is non-zero, receive data 556 * 557 * @param req Pointer to details of the transaction 558 * 559 * @return See \ref MXC_Error_Codes for the list of error return codes. 560 */ 561 int MXC_UART_Transaction(mxc_uart_req_t *req); 562 563 /** 564 * @brief Setup an interrupt-driven UART transaction 565 * 566 * @note The TX FIFO will be filled with txData if necessary 567 * Relevant interrupts will be enabled 568 * 569 * @param req Pointer to details of the transaction 570 * 571 * @return See \ref MXC_Error_Codes for the list of error return codes. 572 */ 573 int MXC_UART_TransactionAsync(mxc_uart_req_t *req); 574 575 /** 576 * @brief Setup a DMA driven UART transaction 577 * 578 * @note The TX FIFO will be filled with txData if necessary 579 * Relevant interrupts will be enabled 580 * The DMA channel indicated by the request will be set up to load/unload the FIFOs 581 * with as few interrupt-based events as possible. The channel will be reset and 582 * returned to the system at the end of the transaction. 583 * 584 * @param req Pointer to details of the transaction 585 * 586 * @return See \ref MXC_Error_Codes for the list of error return codes. 587 */ 588 int MXC_UART_TransactionDMA(mxc_uart_req_t *req); 589 590 /** 591 * @brief The processing function for DMA transactions. 592 * 593 * When using the DMA functions, the application must call this 594 * function periodically. This can be done from within the DMA Interrupt Handler. 595 * 596 * @param ch DMA channel 597 * @param error Error status 598 */ 599 void MXC_UART_DMACallback(int ch, int error); 600 601 /** 602 * @brief Async callback 603 * 604 * @param uart The uart 605 * @param retVal The ret value 606 * 607 * @return See \ref MXC_Error_Codes for the list of error return codes. 608 */ 609 int MXC_UART_AsyncCallback(mxc_uart_regs_t *uart, int retVal); 610 611 /** 612 * @brief stop any async callbacks 613 * 614 * @param uart The uart 615 * 616 * @return See \ref MXC_Error_Codes for the list of error return codes. 617 */ 618 int MXC_UART_AsyncStop(mxc_uart_regs_t *uart); 619 620 /** 621 * @brief Abort any asynchronous requests in progress. 622 * 623 * @note Abort any asynchronous requests in progress. Any callbacks associated with 624 * the active transaction will be executed to indicate when the transaction 625 * has been terminated. 626 * 627 * @param uart Pointer to UART registers (selects the UART block used.) 628 * 629 * @return See \ref MXC_Error_Codes for the list of error return codes. 630 */ 631 int MXC_UART_AbortAsync(mxc_uart_regs_t *uart); 632 633 /** 634 * @brief The processing function for asynchronous transactions. 635 * 636 * @note When using the asynchronous functions, the application must call this 637 * function periodically. This can be done from within the UART interrupt 638 * handler or periodically by the application if UART interrupts are disabled. 639 * 640 * @param uart Pointer to UART registers (selects the UART block used.) 641 * 642 * @return See \ref MXC_Error_Codes for the list of error return codes. 643 */ 644 int MXC_UART_AsyncHandler(mxc_uart_regs_t *uart); 645 646 /** 647 * @brief Enable or disable automatic DMA interrupt handlers for the UART module. 648 * 649 * The @ref MXC_UART_TransactionDMA functions require special interrupt handlers to work. 650 * 651 * When "Auto" DMA handlers are enabled, the UART drivers will acquire DMA channels 652 * and assign the appropriate handlers automatically. The acquired channels are 653 * released after each transaction. 654 * 655 * If "Auto" DMA handlers are disabled, the user must acquire DMA channels manually 656 * and assign them to the drivers with the @ref MXC_UART_SetTXDMAChannel and 657 * @ref MXC_UART_SetRXDMAChannel functions. 658 * 659 * @param uart Pointer to the UART module's registers. 660 * @param enable true to enable Auto DMA handlers, false to disable. 661 * @return 0 on success, or a non-zero error code on failure. 662 */ 663 int MXC_UART_SetAutoDMAHandlers(mxc_uart_regs_t *uart, bool enable); 664 665 /** 666 * @brief Set the TX (Transmit) DMA channel for a UART module. 667 * 668 * This function assigns the DMA channel for transmitting data 669 * when @ref is MXC_UART_SetAutoDMAHandlers disabled. 670 * 671 * @param uart Pointer to the UART module's registers. 672 * @param channel The DMA channel number to be used for @ref MXC_UART_TransactionDMA. 673 */ 674 int MXC_UART_SetTXDMAChannel(mxc_uart_regs_t *uart, unsigned int channel); 675 676 /** 677 * @brief Get the TX (Transmit) DMA channel for a UART module. 678 * 679 * This function retrieves the currently assigned DMA channel for transmitting data 680 * when @ref is MXC_UART_SetAutoDMAHandlers disabled. 681 * 682 * @param uart Pointer to the UART module's registers. 683 * @return The currently assigned TX DMA channel. 684 */ 685 int MXC_UART_GetTXDMAChannel(mxc_uart_regs_t *uart); 686 687 /** 688 * @brief Set the RX (Receive) DMA channel for a UART module. 689 * 690 * This function assigns the DMA channel for receiving data 691 * when @ref is MXC_UART_SetAutoDMAHandlers disabled. 692 * 693 * @param uart Pointer to the UART module's registers. 694 * @param channel The DMA channel number to be used for @ref MXC_UART_TransactionDMA. 695 */ 696 int MXC_UART_SetRXDMAChannel(mxc_uart_regs_t *uart, unsigned int channel); 697 698 /** 699 * @brief Get the RX (Receive) DMA channel for a UART module. 700 * 701 * This function retrieves the currently configured DMA channel for receiving data 702 * when @ref is MXC_UART_SetAutoDMAHandlers disabled. 703 * 704 * @param uart Pointer to the UART module's registers. 705 * @return The currently configured RX DMA channel. 706 */ 707 int MXC_UART_GetRXDMAChannel(mxc_uart_regs_t *uart); 708 709 /**@} end of group uart */ 710 711 #ifdef __cplusplus 712 } 713 #endif 714 715 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32572_UART_H_ 716
