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