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