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