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