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