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