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