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