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